refactor: drop clock option compatibility

apps/docs/docs/management/assistant.mdx

@@ -44,15 +44,12 @@ host gateway address.
 The assistant can work with boards, apps, integrations, widgets, Custom Widgets, and connected services. Use `@` to
 add Homarr items as context, `/` for shortcuts, and the paperclip for supported files.
 
-Use **Conversations** to search, switch, rename, export, or delete threads.
-
 Each request includes the user's name, current page and board, home board, server time, browser time zone, and a small
 summary of accessible Homarr resources. Live status is fetched only when needed.
 
 ## Permissions and privacy
 
-- Read-only actions can run automatically. Changes require approval by default. Automatic approvals apply only to the
-  current conversation, turn off when you switch conversations, and never answer questions for you.
+- Read-only actions can run automatically. Changes require approval.
 - Homarr permissions apply to every tool call and mentioned item.
 - API keys and custom headers are encrypted and never returned to the browser.
 - Conversations are stored per user and can be exported or deleted.

apps/docs/docs/management/logs/index.mdx

@@ -1,34 +0,0 @@
----
-tags:
-  - Administration
-  - Logs
-  - Troubleshooting
----
-
-# Logs
-
-The logs page shows recent Homarr application logs and continues updating as new events occur. Use it to investigate
-widget, integration, and server errors without opening the container logs separately.
-
-## Opening the logs page
-
-Navigate to **Management** > **Tools** > **Logs**. The page and widget log links are only available to users with the
-**View logs** permission.
-
-When a widget reports an error, **Check logs for more details** opens the logs page in a new tab and marks the time when
-the widget displayed the error. The related server error normally appears immediately above that marker. If those logs
-have already been removed from the retained history, the marker explains that they are no longer available.
-
-## Retained and live logs
-
-Homarr retains the latest 5,000 log events in Redis. Opening the page first loads this history and then continues with
-live events without a gap. The history is bounded, so older events are removed automatically.
-
-The history survives normal application restarts when the configured Redis instance persists its data. For complete
-platform-level history, startup failures, or events older than the retained limit, use the logs provided by Docker or
-your deployment platform.
-
-## Display controls
-
-The severity selector applies to both retained and live events. Selecting a different level redraws the existing view
-using that threshold. The font-size control changes the terminal text size and is remembered in the browser.

apps/docs/docs/management/settings/index.mdx

@@ -13,7 +13,7 @@ tags:
 The settings page applies options to the whole Homarr application.
 Some changes need a full page reload before they take effect.
 
-All settings sections remain visible in a single form. Click the **Save changes** button in the save bar at the bottom of the page to apply them. The save bar only appears when you have unsaved changes, and the **Discard** button reverts your changes.
+All changes are collected in a single form. Click the **Save changes** button in the save bar at the bottom of the page to apply them. The save bar only appears when you have unsaved changes, and the **Discard** button reverts your changes.
 
 ## Analytics
 

apps/docs/docs/widgets/air-quality/index.mdx

@@ -0,0 +1,47 @@
+---
+title: "Air Quality & UV"
+description: "Displays air quality, ultraviolet index, pollutants and pollen for a location."
+hide_title: true
+---
+
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { airQualityWidget } from ".";
+
+<WidgetHeader widget={airQualityWidget} categories={["Health", "Weather"]} />
+
+The Air Quality & UV widget shows the current air quality index for a selected location. It adds the UV index,
+dominant pollutant, particulate matter and the highest available pollen reading as space allows. Open the advanced
+view for a 24-hour AQI and UV chart, all available pollutant and pollen readings, and seven-day daily maxima.
+
+Select the European or US AQI scale, or use the automatic setting. Automatic uses the US scale for viewers whose
+locale region is the United States and the European scale everywhere else. The selected scale stays in widget options
+instead of being repeated beside every reading. Pollen values are individual measured concentrations; the widget does
+not combine them into a single pollen index.
+
+The categories and colors summarize published index bands and are not medical advice. Pollutant concentrations use
+micrograms per cubic meter (`µg/m³`), and pollen uses grains per cubic meter.
+
+<WidgetInteractionGuide />
+
+### Adding the widget
+
+<AddingWidget />
+
+### Configuration
+
+<WidgetConfig configuration={airQualityWidget.configuration} />
+
+### Data source
+
+Homarr uses the free Open-Meteo Air Quality API. The widget refreshes active data every 15 minutes and requests a
+seven-day forecast for European AQI, US AQI, UV, particulate matter, ozone, nitrogen dioxide, sulphur dioxide, carbon
+monoxide, and available alder, birch, grass, mugwort, olive and ragweed pollen. Identical location requests reuse the
+server response for 15 minutes. If a refresh fails, Homarr can keep a recent successful response visible for up to 24
+hours instead of replacing it with an empty state.
+
+Set `NO_EXTERNAL_CONNECTION=true` to disable this and other internet-backed requests. If you need to allowlist the
+service, use `https://air-quality-api.open-meteo.com`.

apps/docs/docs/widgets/air-quality/index.ts

@@ -0,0 +1,43 @@
+import type { WidgetDefinition } from "@site/src/types";
+import { IconWind } from "@tabler/icons-react";
+
+export const airQualityWidget: WidgetDefinition = {
+  icon: IconWind,
+  name: "Air Quality & UV",
+  description: "Displays air quality, ultraviolet index, pollutants and pollen for a location.",
+  path: "../../widgets/air-quality",
+  configuration: {
+    items: [
+      {
+        name: "Air quality location",
+        description: "Location used for air quality, UV and pollen data",
+        values: "Select a location through search or longitude/latitude",
+        defaultValue: "Paris / 48.85341, 2.3488",
+      },
+      {
+        name: "AQI standard",
+        description: "Choose the European or US air quality scale, or select one from the viewer's locale",
+        values: { type: "select", options: ["Automatic for locale", "European AQI", "US AQI"] },
+        defaultValue: "Automatic for locale",
+      },
+      {
+        name: "Show UV index",
+        description: "Display the current UV index and its forecast",
+        values: { type: "boolean" },
+        defaultValue: "yes",
+      },
+      {
+        name: "Show pollutant concentrations",
+        description: "Display particulate matter and gaseous pollutant concentrations",
+        values: { type: "boolean" },
+        defaultValue: "yes",
+      },
+      {
+        name: "Show pollen concentrations",
+        description: "Display available pollen concentrations",
+        values: { type: "boolean" },
+        defaultValue: "yes",
+      },
+    ],
+  },
+};

apps/docs/docs/widgets/clock/index.mdx

@@ -15,6 +15,26 @@ import { clockWidget } from ".";
 
 The clock widget displays the current date and time in a customizable format.
 
+Advanced view turns it into a World Clock. The configured primary timezone stays prominent while New York, Paris, and
+Tokyo are included as secondary defaults. You can add, rename, remove, and reorder up to six cities in widget options;
+London, Sydney, and UTC are also available as quick presets.
+
+The digital advanced view keeps the primary timezone prominent and presents every secondary city as a concise,
+comparable card. The primary clock includes a segmented 24-hour rail with a current-time marker, elapsed and remaining
+time, six-hour ticks, and a legend for night, dawn, day, and dusk. These phases are based on local clock time and are not
+astronomical sunrise or sunset calculations. Secondary cards stop after their localized date and timezone offsets.
+
+The compact widget remains a single numeric clock. The time-format selector shows common Day.js presets with live
+examples and applies to the primary clock. Choosing a format with seconds enables second-level updates; 12-hour and
+24-hour display are selected through those same formats. The date-format selector likewise
+shows live Day.js examples and their tokens. Secondary cities always include a short localized date and a
+Yesterday, Today, or Tomorrow label relative to the primary timezone. UTC and relative offsets follow current timezone
+rules, including daylight-saving changes.
+
+Weather remains optional and uses its own configured location rather than a World Clock city. Its icon is static by
+default and can be animated explicitly; reduced-motion preferences always disable animation. An unsupported saved
+timezone is identified without preventing valid clocks from rendering.
+
 ### Screenshots
 
 import localClock from "./img/local.png";
@@ -27,7 +47,7 @@ import tokyoClock from "./img/tokyo-12-hour.png";
   <img src={tokyoClock} alt="clock format-12-hours timezone-tokyo" width={256} height={128} />
 </div>
 
-<WidgetInteractionGuide advancedView={false} />
+<WidgetInteractionGuide />
 
 ### Adding the widget
 

apps/docs/docs/widgets/clock/index.ts

@@ -20,18 +20,6 @@ export const clockWidget: WidgetDefinition = {
         values: { type: "string" },
         defaultValue: "-",
       },
-      {
-        name: "24-hour format",
-        description: "Use 24-hour format instead of 12-hour format.",
-        values: { type: "boolean" },
-        defaultValue: "yes",
-      },
-      {
-        name: "Display seconds",
-        description: "Whether to show seconds in the clock.",
-        values: { type: "boolean" },
-        defaultValue: "no",
-      },
       {
         name: "Use fixed timezone",
         description: "Select custom timezone to display instead of the client timezone.",
@@ -52,21 +40,46 @@ export const clockWidget: WidgetDefinition = {
       },
       {
         name: "Date format",
-        description: "Format of the date displayed below the clock.",
-        values: "A collection of date formats, e.g. 'DD/MM/YYYY', 'MM/DD/YYYY', etc.",
+        description: "Choose a common Day.js date format with a live example and its tokens.",
+        values: "YYYY-MM-DD, DD/MM/YYYY, MM/DD/YYYY, or common long and short date formats",
         defaultValue: "dddd, MMMM D",
       },
       {
-        name: "Custom time format",
-        description: "Format of the time displayed in the clock.",
-        values: 'ISO 8601 format, e.g. "HH:mm:ss", "hh:mm A", etc.',
-        defaultValue: "-",
+        name: "Time format",
+        description:
+          "Choose a common Day.js time format with a live example. The format controls 12/24-hour display and seconds.",
+        values: "HH:mm, HH:mm:ss, h:mm A, or h:mm:ss A",
+        defaultValue: "HH:mm",
       },
       {
-        name: "Custom date format",
-        description: "Format of the date displayed below the clock.",
-        values: 'ISO 8601 format, e.g. "YYYY-MM-DD", "DD/MM/YYYY", etc.',
-        defaultValue: "-",
+        name: "Show weather",
+        description: "Show a compact weather summary from an independently configured location.",
+        values: { type: "boolean" },
+        defaultValue: "no",
+      },
+      {
+        name: "Weather location",
+        description: 'Location used by the weather summary. Only shown if "Show weather" is enabled.',
+        values: "A searched city or custom latitude and longitude",
+        defaultValue: "Brisbane",
+      },
+      {
+        name: "Use Fahrenheit",
+        description: 'Use Fahrenheit in the weather summary. Only shown if "Show weather" is enabled.',
+        values: { type: "boolean" },
+        defaultValue: "no",
+      },
+      {
+        name: "Animate weather icon",
+        description: "Animate the weather icon unless the device requests reduced motion.",
+        values: { type: "boolean" },
+        defaultValue: "no",
+      },
+      {
+        name: "World clock cities",
+        description: "Add, label, and order up to six IANA timezones for advanced view.",
+        values: "Up to six labeled IANA timezones",
+        defaultValue: "New York, Paris, and Tokyo",
       },
     ],
   },

apps/docs/docs/widgets/countdown/index.mdx

@@ -0,0 +1,44 @@
+---
+title: "Countdowns"
+description: "Tracks upcoming events and recurring anniversaries."
+hide_title: true
+---
+
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { countdownWidget } from ".";
+
+<WidgetHeader widget={countdownWidget} categories={["Time"]} />
+
+The Countdowns widget tracks up to 20 events without an integration. Add each event in widget options, choose its local
+date and time, and select an IANA timezone. Events can be reordered by dragging them.
+
+The compact widget shows the first configured event, so dragging an event to the top selects the countdown displayed on
+the board. Advanced view uses that same event for its larger summary and preserves the configured order within its
+upcoming and completed groups. List cards keep their occurrence date at the bottom, below the optional progress bar.
+
+One-time events remain completed after their target. A yearly event keeps the same local date and wall-clock time in its
+configured timezone, including when daylight-saving offsets change. A February 29 event waits until the next leap year.
+If a configured local time falls in a daylight-saving gap, the first valid time afterward is used; if it occurs twice,
+the earlier occurrence is used.
+
+Progress is optional. One-time events need a start date before a percentage can be calculated. Yearly events show
+progress from the previous occurrence to the next. When enabled, seconds remain visible for every upcoming event.
+
+Browser notifications are an optional local preference in advanced view and are disabled by default. Permission is
+requested only after you enable notifications, and alerts can fire once per occurrence while Homarr is open. Browser
+storage uses the board and widget identifiers to keep preferences separate and prevent duplicate alerts; clearing site
+data resets them. Widget previews do not persist alert preferences.
+
+<WidgetInteractionGuide />
+
+### Adding the widget
+
+<AddingWidget />
+
+### Configuration
+
+<WidgetConfig configuration={countdownWidget.configuration} />

apps/docs/docs/widgets/countdown/index.ts

@@ -0,0 +1,31 @@
+import { WidgetDefinition } from "@site/src/types";
+import { IconHourglass } from "@tabler/icons-react";
+
+export const countdownWidget: WidgetDefinition = {
+  icon: IconHourglass,
+  name: "Countdowns",
+  description: "Tracks upcoming events and recurring anniversaries.",
+  path: "../../widgets/countdown",
+  configuration: {
+    items: [
+      {
+        name: "Events",
+        description: "Add, edit, and order one-time or yearly events with a date, time, and IANA timezone.",
+        values: "Up to 20 events",
+        defaultValue: "No events",
+      },
+      {
+        name: "Show progress",
+        description: "Show progress from an optional start date, or between yearly occurrences.",
+        values: { type: "boolean" },
+        defaultValue: "yes",
+      },
+      {
+        name: "Show seconds",
+        description: "Keep seconds visible for every upcoming event, including events more than a day away.",
+        values: { type: "boolean" },
+        defaultValue: "no",
+      },
+    ],
+  },
+};

apps/docs/docs/widgets/timer/index.mdx

@@ -0,0 +1,54 @@
+---
+title: "Timer / Pomodoro"
+description: "Runs a simple timer or a configurable Pomodoro sequence."
+hide_title: true
+---
+
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { timerWidget } from ".";
+
+<WidgetHeader widget={timerWidget} categories={["Productivity", "Time"]} />
+
+The Timer / Pomodoro widget runs entirely in your browser and does not require an integration. The compact widget
+always keeps its start or pause button and reset button visible. A running timer uses a saved deadline, so reopening
+the board or returning to a background tab restores the correct remaining time instead of restarting the countdown.
+
+Timer mode uses one configured duration. Pomodoro mode starts with a focus session, follows most completed focus
+sessions with a short break, and uses a long break after the configured number of focus sessions. Automatic break and
+focus starts are separate options and are disabled by default. When automatic starts are enabled, elapsed phases are
+reconciled from their original deadlines after the board returns to the foreground.
+
+Advanced view shows the current sequence, configured durations, and local alert preferences. Browser notifications are
+requested only when enabled. Notification and sound preferences, live progress, deadlines, and cycle position are
+stored locally using the board and widget identifiers. They are separate for each browser or device, are available to
+guest viewers, and are removed by clearing site data. Widget previews are ephemeral and do not write local timer state.
+
+Timer sounds are enabled by default and use the same low-volume Tiks sound system as onboarding: start and pause use
+rising and falling soft-theme cues, reset uses a short click, and phase completion uses the glass theme's resonant
+notification ding. You can disable them in advanced view. The cues respect the device's reduced-motion preference and
+supplement the visible timer state rather than replacing it.
+
+When automatic start is disabled, a completed phase labels the next step as ready and flashes the widget edges with the
+board's secondary color. The border glow and completion chime run together as a five-beat alarm burst at
+300-millisecond intervals, then stop. Reduced-motion and forced-colors modes replace the flash with a static border.
+The current phase stays pinned to the compact widget's top-left corner and wraps when needed. Timer text and controls
+use the dashboard theme's responsive size scale, with secondary details hidden when the widget preview is narrow or
+short.
+
+Alerts can fire while Homarr is open. Browser and operating-system notification settings may still suppress them.
+The timer's mode, durations, session count, and automatic-start behavior are permanent board settings and are edited
+from the widget context menu.
+
+<WidgetInteractionGuide />
+
+### Adding the widget
+
+<AddingWidget />
+
+### Configuration
+
+<WidgetConfig configuration={timerWidget.configuration} />

apps/docs/docs/widgets/timer/index.ts

@@ -0,0 +1,61 @@
+import type { WidgetDefinition } from "@site/src/types";
+import { IconClockPlay } from "@tabler/icons-react";
+
+export const timerWidget: WidgetDefinition = {
+  icon: IconClockPlay,
+  name: "Timer / Pomodoro",
+  description: "Runs a simple timer or a configurable Pomodoro sequence.",
+  path: "../../widgets/timer",
+  configuration: {
+    items: [
+      {
+        name: "Mode",
+        description: "Run one reusable timer or a repeating focus and break sequence",
+        values: { type: "select", options: ["Timer", "Pomodoro"] },
+        defaultValue: "Pomodoro",
+      },
+      {
+        name: "Timer minutes",
+        description: "Duration of the reusable timer",
+        values: "1-1440 minutes",
+        defaultValue: "10",
+      },
+      {
+        name: "Focus minutes",
+        description: "Duration of each Pomodoro focus session",
+        values: "1-180 minutes",
+        defaultValue: "25",
+      },
+      {
+        name: "Short break minutes",
+        description: "Duration of breaks between most focus sessions",
+        values: "1-60 minutes",
+        defaultValue: "5",
+      },
+      {
+        name: "Long break minutes",
+        description: "Duration of the break at the end of a Pomodoro cycle",
+        values: "1-180 minutes",
+        defaultValue: "15",
+      },
+      {
+        name: "Focus sessions before a long break",
+        description: "Number of completed focus sessions in one Pomodoro cycle",
+        values: "1-12 sessions",
+        defaultValue: "4",
+      },
+      {
+        name: "Automatically start breaks",
+        description: "Start the next short or long break when a focus session completes",
+        values: { type: "boolean" },
+        defaultValue: "no",
+      },
+      {
+        name: "Automatically start focus sessions",
+        description: "Start the next focus session when a break completes",
+        values: { type: "boolean" },
+        defaultValue: "no",
+      },
+    ],
+  },
+};

apps/docs/docs/widgets/today/index.mdx

@@ -0,0 +1,34 @@
+---
+title: "Today"
+description: "Displays the current date and progress through the calendar."
+hide_title: true
+---
+
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { todayWidget } from ".";
+
+<WidgetHeader widget={todayWidget} categories={["Date", "Time"]} />
+
+The Today widget presents the current local date without duplicating a live clock. It progressively adds the week
+number, day of year, quarter, remaining days, and calendar progress as more space becomes available.
+
+The advanced view shows week, month, and year progress together with a twelve-month overview. Week numbers can follow
+your locale or the ISO 8601 convention. “Days after today” excludes the current day to keep the remaining-day count
+unambiguous.
+
+The widget runs entirely in your browser and does not send date or location data to an external service. It follows
+the timezone and locale of the device viewing the board, so viewers in different regions can see their own local date.
+
+<WidgetInteractionGuide />
+
+### Adding the widget
+
+<AddingWidget />
+
+### Configuration
+
+<WidgetConfig configuration={todayWidget.configuration} />

apps/docs/docs/widgets/today/index.ts

@@ -0,0 +1,43 @@
+import type { WidgetDefinition } from "@site/src/types";
+import { IconCalendarWeek } from "@tabler/icons-react";
+
+export const todayWidget: WidgetDefinition = {
+  icon: IconCalendarWeek,
+  name: "Today",
+  description: "Displays the current date and progress through the calendar.",
+  path: "../../widgets/today",
+  configuration: {
+    items: [
+      {
+        name: "Week numbering",
+        description: "Use locale-specific week numbering or ISO 8601 week numbers",
+        values: { type: "select", options: ["Use locale rules", "ISO 8601"] },
+        defaultValue: "Use locale rules",
+      },
+      {
+        name: "Show week number",
+        description: "Display the current week number when the widget has room",
+        values: { type: "boolean" },
+        defaultValue: "yes",
+      },
+      {
+        name: "Show day of year",
+        description: "Display the current day number within the year",
+        values: { type: "boolean" },
+        defaultValue: "yes",
+      },
+      {
+        name: "Show quarter",
+        description: "Display the current calendar quarter",
+        values: { type: "boolean" },
+        defaultValue: "yes",
+      },
+      {
+        name: "Show year progress",
+        description: "Display progress through the current year",
+        values: { type: "boolean" },
+        defaultValue: "yes",
+      },
+    ],
+  },
+};

apps/docs/docs/widgets/weather/index.mdx

@@ -13,23 +13,21 @@ import { weatherWidget } from ".";
 
 <WidgetHeader widget={weatherWidget} categories={["Weather"]} />
 
-The Weather Widget uses your location to display the current, highest and lowest temperature.
-In the compact view, select a condition icon or forecast day to open details with a mouse, keyboard or touch.
-The compact forecast shows up to the configured number of days. The advanced view combines current conditions with the
-available daily forecast, including humidity, wind, gusts, sunrise and sunset. Both views reuse the same cached Open
-Meteo response.
+The Weather Widget displays current conditions and a responsive forecast for a selected location. New widgets start
+with the city and a three-day forecast visible. As the widget gets smaller, it keeps the current condition and
+temperature readable before removing secondary details or forecast days.
 
-### Screenshots
+Select a forecast day to inspect precipitation, apparent temperature, humidity, wind, UV index, sunrise, sunset and
+daylight duration with a mouse, keyboard or touch. Open the advanced view for a current-condition summary, a 24-hour
+temperature and precipitation chart, and the complete seven-day forecast. The chart has an equivalent data table for
+assistive technologies.
 
-import forecastWeather from "./img/forecast.png";
-import currentWeather from "./img/current.png";
-import advancedWeather from "./img/advanced-view.png";
+The **Show humidity** option controls humidity across the compact current-conditions view, advanced summary, hourly
+details, and daily forecast details. Forecast cards use a roomier adaptive grid in advanced view, with four columns on
+the standard desktop surface and fewer columns as the surface narrows.
 
-<div className="flex flex-col gap-1">
-  <img src={forecastWeather} alt="Weather compact forecast" width={238} height={112} />
-  <img src={currentWeather} alt="Weather compact current conditions" width={198} height={93} />
-  <img src={advancedWeather} alt="Weather advanced view with seven-day forecast details" width={800} height={484} />
-</div>
+Weather icons are static by default. Animation can be enabled in the widget configuration, but the operating system's
+reduced-motion preference always disables it.
 
 <WidgetInteractionGuide />
 
@@ -43,5 +41,10 @@ import advancedWeather from "./img/advanced-view.png";
 
 ### Data source
 
-We use the Open Meteo API to fetch the weather and locations.
+We use the Open Meteo API to fetch the weather and locations. Active weather data refreshes every ten minutes, while
+identical location requests can reuse a server response for five minutes. A manual refresh may therefore return the
+same still-current server response. If a refresh fails, Homarr keeps the last successful data visible and shows an
+error indicator.
+
+Set `NO_EXTERNAL_CONNECTION=true` to disable this and other internet-backed requests.
 If you need to whitelist the api, please use the following URL: `https://open-meteo.com`

apps/docs/docs/widgets/weather/index.tsx

@@ -28,8 +28,24 @@ export const weatherWidget: WidgetDefinition = {
         values: {
           type: "boolean",
         },
+        defaultValue: "no",
+      },
+      {
+        name: "Show humidity",
+        description: "Display humidity in current conditions, hourly details, and daily forecasts",
+        values: {
+          type: "boolean",
+        },
         defaultValue: "yes",
       },
+      {
+        name: "Animate weather icons",
+        description: "Animate condition icons unless the operating system requests reduced motion",
+        values: {
+          type: "boolean",
+        },
+        defaultValue: "no",
+      },
       {
         name: "Use imperial speed units",
         description: "Display wind speed in mph instead of km/h",
@@ -59,7 +75,7 @@ export const weatherWidget: WidgetDefinition = {
         values: {
           type: "boolean",
         },
-        defaultValue: "no",
+        defaultValue: "yes",
       },
       {
         name: "Has forecast",
@@ -67,13 +83,13 @@ export const weatherWidget: WidgetDefinition = {
         values: {
           type: "boolean",
         },
-        defaultValue: "no",
+        defaultValue: "yes",
       },
       {
         name: "Amount of forecast days",
         description: "Number of days to show in the forecast",
         values: "1-7",
-        defaultValue: "5",
+        defaultValue: "3",
       },
     ],
   },

apps/docs/src/components/pages/home/hero/widgets/weather-widget.tsx

@@ -1,4 +1,4 @@
-import { IconCloud, IconWind, IconArrowUpRight, IconArrowDownRight } from "@tabler/icons-react";
+import { IconCloud, IconCloudRain, IconSun } from "@tabler/icons-react";
 import { CommonWidgetProps, WidgetCard } from "./card";
 import clsx from "clsx";
 
@@ -6,21 +6,27 @@ export const WeatherWidget = ({ className }: CommonWidgetProps) => {
   return (
     <WidgetCard width={1} className={clsx("gap-2", className)}>
       <div className="flex gap-2 justify-center items-center">
-        <IconCloud size={20} />
-        <span className="text-xl font-bold">10.8°C</span>
-      </div>
-      <div className="flex gap-2 justify-center items-center">
-        <IconWind size={14} />
-        <span className="text-sm">5 km/h</span>
-      </div>
-      <div className="flex gap-1 justify-center items-center">
-        <div className="flex justify-center items-center">
-          <IconArrowUpRight size={14} />
-          <span className="text-sm">13.5°C</span>
+        <IconSun size={22} />
+        <div className="flex flex-col leading-none">
+          <span className="text-xl font-bold">18.4°C</span>
+          <span className="text-xs text-muted-foreground">Paris</span>
         </div>
-        <div className="flex justify-center items-center">
-          <IconArrowDownRight size={14} />
-          <span className="text-sm">6.4°C</span>
+      </div>
+      <div className="flex justify-evenly items-center w-full">
+        <div className="flex flex-col items-center text-xs">
+          <span>Mon</span>
+          <IconSun size={16} />
+          <span>21°</span>
+        </div>
+        <div className="flex flex-col items-center text-xs">
+          <span>Tue</span>
+          <IconCloud size={16} />
+          <span>19°</span>
+        </div>
+        <div className="flex flex-col items-center text-xs">
+          <span>Wed</span>
+          <IconCloudRain size={16} />
+          <span>16°</span>
         </div>
       </div>
     </WidgetCard>

apps/docs/static/api/open-api-schema.json

@@ -2106,6 +2106,10 @@
                     "enum": [
                       "clock",
                       "weather",
+                      "today",
+                      "airQuality",
+                      "countdown",
+                      "timer",
                       "app",
                       "iframe",
                       "video",

apps/nextjs/src/app/[locale]/manage/settings/_components/appearance-settings-form.tsx

@@ -29,7 +29,6 @@ export const AppearanceSettingsForm = ({ form }: AppearanceSettingsFormProps) =>
         }))}
         {...form.getInputProps("defaultColorScheme")}
         SelectOption={AppearanceCustomOption}
-        withinPortal
       />
     </SectionCard>
   );

apps/nextjs/src/app/[locale]/manage/settings/_components/board-settings-form.tsx

@@ -2,7 +2,7 @@
 
 import { Switch, Text } from "@mantine/core";
 
-import type { RouterOutputs } from "@homarr/api";
+import { clientApi } from "@homarr/api/client";
 import type { UseFormReturnType } from "@homarr/form";
 import { useScopedI18n } from "@homarr/translation/client";
 
@@ -12,11 +12,11 @@ import type { FormValues } from "./settings-form";
 
 interface BoardSettingsFormProps {
   form: UseFormReturnType<FormValues>;
-  selectableBoards: RouterOutputs["board"]["getPublicBoards"];
 }
 
-export const BoardSettingsForm = ({ form, selectableBoards }: BoardSettingsFormProps) => {
+export const BoardSettingsForm = ({ form }: BoardSettingsFormProps) => {
   const tBoard = useScopedI18n("management.page.settings.section.board");
+  const [selectableBoards] = clientApi.board.getPublicBoards.useSuspenseQuery();
 
   return (
     <SectionCard title={tBoard("title")}>
@@ -26,7 +26,6 @@ export const BoardSettingsForm = ({ form, selectableBoards }: BoardSettingsFormP
         clearable
         boards={selectableBoards}
         {...form.getInputProps("homeBoardId")}
-        withinPortal
       />
 
       <BoardSelect
@@ -35,7 +34,6 @@ export const BoardSettingsForm = ({ form, selectableBoards }: BoardSettingsFormP
         clearable
         boards={selectableBoards}
         {...form.getInputProps("mobileHomeBoardId")}
-        withinPortal
       />
 
       <Text fw={500}>{tBoard("status.title")}</Text>

apps/nextjs/src/app/[locale]/manage/settings/_components/culture-settings-form.tsx

@@ -22,7 +22,6 @@ export const CultureSettingsForm = ({ form }: CultureSettingsFormProps) => {
         label={tCulture("defaultLocale.label")}
         {...localeInputProps}
         value={localeInputProps.value as SupportedLanguage}
-        withinPortal
       />
     </SectionCard>
   );

apps/nextjs/src/app/[locale]/manage/settings/_components/search-settings-form.tsx

@@ -2,7 +2,7 @@
 
 import { Select } from "@mantine/core";
 
-import type { RouterOutputs } from "@homarr/api";
+import { clientApi } from "@homarr/api/client";
 import type { UseFormReturnType } from "@homarr/form";
 import { useScopedI18n } from "@homarr/translation/client";
 
@@ -11,11 +11,11 @@ import type { FormValues } from "./settings-form";
 
 interface SearchSettingsFormProps {
   form: UseFormReturnType<FormValues>;
-  selectableSearchEngines: RouterOutputs["searchEngine"]["getSelectable"];
 }
 
-export const SearchSettingsForm = ({ form, selectableSearchEngines }: SearchSettingsFormProps) => {
+export const SearchSettingsForm = ({ form }: SearchSettingsFormProps) => {
   const tSearch = useScopedI18n("management.page.settings.section.search");
+  const [selectableSearchEngines] = clientApi.searchEngine.getSelectable.useSuspenseQuery({ withIntegrations: false });
 
   return (
     <SectionCard title={tSearch("title")}>

apps/nextjs/src/app/[locale]/manage/settings/_components/settings-form.tsx

@@ -4,7 +4,6 @@ import { useEffect, useRef, useState } from "react";
 import { Button, Stack } from "@mantine/core";
 import { z } from "zod/v4";
 
-import type { RouterOutputs } from "@homarr/api";
 import { clientApi } from "@homarr/api/client";
 import { revalidatePathActionAsync } from "@homarr/common/client";
 import { env } from "@homarr/common/env";
@@ -59,11 +58,9 @@ const buildInitialValues = (initialData: ServerSettings): FormValues => ({
 
 interface SettingsFormProps {
   initialData: ServerSettings;
-  selectableBoards: RouterOutputs["board"]["getPublicBoards"];
-  selectableSearchEngines: RouterOutputs["searchEngine"]["getSelectable"];
 }
 
-export const SettingsForm = ({ initialData, selectableBoards, selectableSearchEngines }: SettingsFormProps) => {
+export const SettingsForm = ({ initialData }: SettingsFormProps) => {
   const t = useI18n();
   const tSettings = useScopedI18n("management.page.settings");
 
@@ -172,13 +169,13 @@ export const SettingsForm = ({ initialData, selectableBoards, selectableSearchEn
   return (
     <form onSubmit={form.onSubmit((values) => void handleSubmitAsync(values))}>
       <Stack gap="xl">
-        <BoardSettingsForm form={form} selectableBoards={selectableBoards} />
-        <UserSettingsForm form={form} />
-        <SearchSettingsForm form={form} selectableSearchEngines={selectableSearchEngines} />
-        <AppearanceSettingsForm form={form} />
-        <CultureSettingsForm form={form} />
         <AnalyticsSettings form={form} />
         <CrawlingAndIndexingSettings form={form} />
+        <BoardSettingsForm form={form} />
+        <UserSettingsForm form={form} />
+        <SearchSettingsForm form={form} />
+        <AppearanceSettingsForm form={form} />
+        <CultureSettingsForm form={form} />
 
         {form.isDirty() && (
           <UnsavedChangesBar>

apps/nextjs/src/app/[locale]/manage/settings/page.tsx

@@ -23,20 +23,12 @@ export default async function SettingsPage() {
     notFound();
   }
 
-  const [serverSettings, selectableBoards, selectableSearchEngines, tSettings] = await Promise.all([
-    api.serverSettings.getAll(),
-    api.board.getPublicBoards(),
-    api.searchEngine.getSelectable({ withIntegrations: false }),
-    getScopedI18n("management.page.settings"),
-  ]);
+  const serverSettings = await api.serverSettings.getAll();
+  const tSettings = await getScopedI18n("management.page.settings");
 
   return (
     <ManagePageLayout title={tSettings("title")}>
-      <SettingsForm
-        initialData={serverSettings}
-        selectableBoards={selectableBoards}
-        selectableSearchEngines={selectableSearchEngines}
-      />
+      <SettingsForm initialData={serverSettings} />
     </ManagePageLayout>
   );
 }

apps/nextjs/src/app/[locale]/manage/tools/logs/client.tsx

@@ -2,11 +2,7 @@
 
 import dynamic from "next/dynamic";
 
-interface ClientSideTerminalComponentProps {
-  focusTimestamp?: number;
-}
-
-export const ClientSideTerminalComponent = dynamic<ClientSideTerminalComponentProps>(
+export const ClientSideTerminalComponent = dynamic(
   () => import("./terminal").then(({ TerminalComponent }) => TerminalComponent),
   {
     ssr: false,

apps/nextjs/src/app/[locale]/manage/tools/logs/page.tsx

@@ -29,25 +29,12 @@ export async function generateMetadata() {
   };
 }
 
-interface LogsManagementPageProps {
-  searchParams: Promise<{ focus?: string | string[] }>;
-}
-
-export default async function LogsManagementPage({ searchParams }: LogsManagementPageProps) {
+export default async function LogsManagementPage() {
   const session = await auth();
   if (!session?.user.permissions.includes("other-view-logs")) {
     notFound();
   }
 
-  const focus = (await searchParams).focus;
-  let focusTimestamp: number | undefined;
-  if (typeof focus === "string") {
-    const parsedFocusTimestamp = Number(focus);
-    if (Number.isSafeInteger(parsedFocusTimestamp) && parsedFocusTimestamp > 0) {
-      focusTimestamp = parsedFocusTimestamp;
-    }
-  }
-
   return (
     <LogContextProvider defaultLevel={logsEnv.LEVEL}>
       <Group justify="space-between" align="center" wrap="nowrap">
@@ -58,7 +45,7 @@ export default async function LogsManagementPage({ searchParams }: LogsManagemen
         </Group>
       </Group>
       <Box style={{ borderRadius: 6 }} h={fullHeightWithoutHeaderAndFooter} p="md" bg="black">
-        <ClientSideTerminalComponent focusTimestamp={focusTimestamp} />
+        <ClientSideTerminalComponent />
       </Box>
     </LogContextProvider>
   );

apps/nextjs/src/app/[locale]/manage/tools/logs/terminal.tsx

@@ -7,163 +7,25 @@ import { FitAddon } from "@xterm/addon-fit";
 import { Terminal } from "@xterm/xterm";
 
 import { clientApi } from "@homarr/api/client";
-import type { LoggerMessage, LogLevel } from "@homarr/core/infrastructure/logs/constants";
-import { LOG_HISTORY_MAX_ENTRIES, logLevels } from "@homarr/core/infrastructure/logs/constants";
-import { useI18n } from "@homarr/translation/client";
 
 import { useLogContext } from "./log-context";
 import classes from "./terminal.module.css";
 
-const ALL_LOG_LEVELS = [...logLevels];
-const TERMINAL_SCROLLBACK_LINES = LOG_HISTORY_MAX_ENTRIES * 20;
-
-const getFocusMarker = (
-  messages: LoggerMessage[],
-  visibleMessages: LoggerMessage[],
-  focusTimestamp: number | undefined,
-  markerText: string,
-  expiredMarkerText: string,
-) => {
-  if (focusTimestamp === undefined) return null;
-
-  const oldestTimestamp = messages[0]?.timestamp.getTime();
-  if (oldestTimestamp === undefined || focusTimestamp < oldestTimestamp) {
-    return { index: 0, text: expiredMarkerText };
-  }
-
-  return {
-    index: visibleMessages.findLastIndex((message) => message.timestamp.getTime() <= focusTimestamp) + 1,
-    text: markerText,
-  };
-};
-
-const findMarkerLine = (terminal: Terminal, linesFromEnd: number) => {
-  const buffer = terminal.buffer.active;
-  const logicalLineStarts: number[] = [];
-  const cursorLine = buffer.baseY + buffer.cursorY;
-
-  for (let index = 0; index <= cursorLine; index++) {
-    const line = buffer.getLine(index);
-    if (!line) continue;
-
-    if (!line.isWrapped) {
-      logicalLineStarts.push(index);
-    }
-  }
-
-  return logicalLineStarts.at(-linesFromEnd) ?? null;
-};
-
-const renderMessages = ({
-  terminal,
-  messages,
-  activeLevels,
-  focusTimestamp,
-  markerText,
-  expiredMarkerText,
-}: {
-  terminal: Terminal;
-  messages: LoggerMessage[];
-  activeLevels: LogLevel[];
-  focusTimestamp: number | undefined;
-  markerText: string;
-  expiredMarkerText: string;
-}) => {
-  const activeLevelSet = new Set(activeLevels);
-  const visibleMessages = messages.filter((message) => activeLevelSet.has(message.level));
-  const focusMarker = getFocusMarker(messages, visibleMessages, focusTimestamp, markerText, expiredMarkerText);
-  const output: string[] = [];
-  let markerOutputIndex: number | null = null;
-
-  visibleMessages.forEach((message, index) => {
-    if (focusMarker?.index === index) {
-      markerOutputIndex = output.length;
-      output.push(`\x1b[33m--- ${focusMarker.text} ---\x1b[0m`);
-    }
-    output.push(message.message);
-  });
-
-  if (focusMarker?.index === visibleMessages.length) {
-    markerOutputIndex = output.length;
-    output.push(`\x1b[33m--- ${focusMarker.text} ---\x1b[0m`);
-  }
-
-  let markerLinesFromEnd: number | null = null;
-  if (markerOutputIndex !== null) {
-    markerLinesFromEnd =
-      1 + output.slice(markerOutputIndex).reduce((lineCount, line) => lineCount + line.split(/\r?\n/).length, 0);
-  }
-
-  terminal.write(`\x1bc${output.join("\r\n")}${output.length > 0 ? "\r\n" : ""}`, () => {
-    if (markerLinesFromEnd === null) {
-      terminal.scrollToBottom();
-      return;
-    }
-
-    const markerLine = findMarkerLine(terminal, markerLinesFromEnd);
-    if (markerLine !== null) {
-      terminal.scrollToLine(markerLine);
-    }
-  });
-};
-
-interface TerminalComponentProps {
-  focusTimestamp?: number;
-}
-
-export const TerminalComponent = ({ focusTimestamp }: TerminalComponentProps) => {
+export const TerminalComponent = () => {
   const ref = useRef<HTMLDivElement>(null);
   const { activeLevels, fontSize } = useLogContext();
-  const t = useI18n();
 
   const terminalRef = useRef<Terminal>(null);
   const fitAddonRef = useRef<FitAddon>(null);
-  const messagesRef = useRef<LoggerMessage[]>([]);
-  const initialFontSizeRef = useRef(fontSize);
-  const activeLevelsRef = useRef(activeLevels);
-  const markerTextRef = useRef("");
-  const expiredMarkerTextRef = useRef("");
-  const focusTimestampRef = useRef(focusTimestamp);
-
-  activeLevelsRef.current = activeLevels;
-  markerTextRef.current = t("log.context.widgetError");
-  expiredMarkerTextRef.current = t("log.context.expiredWidgetError");
-  focusTimestampRef.current = focusTimestamp;
-
-  const redrawTerminal = () => {
-    const terminal = terminalRef.current;
-    if (!terminal) return;
-
-    renderMessages({
-      terminal,
-      messages: messagesRef.current,
-      activeLevels: activeLevelsRef.current,
-      focusTimestamp: focusTimestampRef.current,
-      markerText: markerTextRef.current,
-      expiredMarkerText: expiredMarkerTextRef.current,
-    });
-  };
 
   clientApi.log.subscribe.useSubscription(
     {
-      levels: ALL_LOG_LEVELS,
+      levels: activeLevels,
     },
     {
-      onData(event) {
-        if (event.type === "history") {
-          messagesRef.current = event.messages.slice(-LOG_HISTORY_MAX_ENTRIES);
-          redrawTerminal();
-          return;
-        }
-
-        messagesRef.current.push(event.message);
-        if (messagesRef.current.length > LOG_HISTORY_MAX_ENTRIES) {
-          messagesRef.current.shift();
-        }
-
-        if (activeLevelsRef.current.includes(event.message.level)) {
-          terminalRef.current?.writeln(event.message.message);
-        }
+      onData(data) {
+        terminalRef.current?.writeln(data.message);
+        terminalRef.current?.refresh(0, terminalRef.current.rows - 1);
       },
       onError(err) {
         alert(err);
@@ -182,26 +44,22 @@ export const TerminalComponent = ({ focusTimestamp }: TerminalComponentProps) =>
       cursorBlink: false,
       disableStdin: true,
       convertEol: true,
-      fontSize: initialFontSizeRef.current,
-      scrollback: TERMINAL_SCROLLBACK_LINES,
+      fontSize,
     });
     terminalRef.current.open(ref.current);
     terminalRef.current.loadAddon(canvasAddon);
 
-    const fitTimeout = window.setTimeout(() => {
+    setTimeout(() => {
       const fitAddon = new FitAddon();
       fitAddonRef.current = fitAddon;
       terminalRef.current?.loadAddon(fitAddon);
       fitAddon.fit();
-      redrawTerminal();
     });
 
     return () => {
-      window.clearTimeout(fitTimeout);
       canvasAddon.dispose();
       terminalRef.current?.dispose();
       terminalRef.current = null;
-      fitAddonRef.current = null;
     };
   }, []);
 
@@ -211,9 +69,5 @@ export const TerminalComponent = ({ focusTimestamp }: TerminalComponentProps) =>
     fitAddonRef.current?.fit();
   }, [fontSize]);
 
-  useEffect(() => {
-    redrawTerminal();
-  }, [activeLevels, focusTimestamp]);
-
   return <Box ref={ref} id="terminal" className={classes.outerTerminal} h="100%"></Box>;
 };

apps/nextjs/src/components/assistant/assistant-auto-approval.spec.ts

@@ -104,46 +104,6 @@ describe("assistant automatic approval tracker", () => {
     await act(async () => root.unmount());
   });
 
-  test("does not approve a ready action while switching conversations", async () => {
-    const container = document.createElement("div");
-    containers.push(container);
-    document.body.append(container);
-    const root = createRoot(container);
-    let confirmationCount = 0;
-    const renderConversation = async (conversationId: string, ready: boolean) => {
-      await act(async () => {
-        root.render(
-          createElement(
-            AssistantAutoApprovalProvider,
-            { conversationId },
-            createElement(
-              Fragment,
-              null,
-              createElement(AutoApprovalProbe),
-              createElement(AutomaticActionProbe, {
-                ready,
-                completed: false,
-                confirm: () => {
-                  confirmationCount += 1;
-                },
-              }),
-            ),
-          ),
-        );
-      });
-    };
-
-    await renderConversation("local-thread-1", false);
-    act(() => currentAutoApproval?.setEnabled(true));
-    await renderConversation("local-thread-2", true);
-
-    expect(confirmationCount).toBe(0);
-    expect(currentAutoApproval?.enabled).toBe(false);
-    expect(automaticActionInProgress).toBe(false);
-
-    await act(async () => root.unmount());
-  });
-
   test("clears claimed calls when automatic approvals are turned off", async () => {
     const container = document.createElement("div");
     containers.push(container);

apps/nextjs/src/components/assistant/assistant-auto-approval.tsx

@@ -52,8 +52,6 @@ export const AssistantAutoApprovalProvider = ({
   const trackerRef = useRef(createAssistantAutoApprovalTracker(AUTO_APPROVAL_MAX_ATTEMPTS));
   const retryTimersRef = useRef(new Map<string, number>());
   const previousConversationIdRef = useRef(conversationId);
-  const conversationMatches = previousConversationIdRef.current === conversationId;
-  const effectiveEnabled = conversationMatches && enabled;
 
   const clearRetryTimer = useCallback((toolCallId: string) => {
     const timer = retryTimersRef.current.get(toolCallId);
@@ -88,7 +86,7 @@ export const AssistantAutoApprovalProvider = ({
 
   const requestAction = useCallback(
     (toolCallId: string, confirm: () => void) => {
-      if (!effectiveEnabled || !trackerRef.current.claim(toolCallId)) return false;
+      if (!enabled || !trackerRef.current.claim(toolCallId)) return false;
 
       try {
         confirm();
@@ -107,7 +105,7 @@ export const AssistantAutoApprovalProvider = ({
         return false;
       }
     },
-    [clearRetryTimer, effectiveEnabled],
+    [clearRetryTimer, enabled],
   );
 
   const completeAction = useCallback(
@@ -118,15 +116,10 @@ export const AssistantAutoApprovalProvider = ({
     [clearRetryTimer],
   );
 
-  const value = useMemo(() => {
-    return {
-      enabled: effectiveEnabled,
-      setEnabled,
-      requestAction,
-      completeAction,
-      retryRevision,
-    };
-  }, [completeAction, effectiveEnabled, requestAction, retryRevision, setEnabled]);
+  const value = useMemo(
+    () => ({ enabled, setEnabled, requestAction, completeAction, retryRevision }),
+    [completeAction, enabled, requestAction, retryRevision, setEnabled],
+  );
 
   return <AssistantAutoApprovalContext.Provider value={value}>{children}</AssistantAutoApprovalContext.Provider>;
 };

apps/nextjs/src/components/assistant/assistant-context.tsx

@@ -20,15 +20,11 @@ export interface AssistantContextValue {
   isRunning: boolean;
   isRefreshing: boolean;
   unreadCount: number;
-  hasVisibleWidget: boolean;
-  activeWidgetId: string | null;
   open: () => void;
   close: () => void;
   toggle: () => void;
   sendPrompt: (prompt: string) => boolean;
   refreshCurrentView: () => Promise<void>;
-  setWidgetVisible: (widgetId: string, visible: boolean) => void;
-  activateWidget: (widgetId: string) => void;
 }
 
 export const AssistantContext = createContext<AssistantContextValue | null>(null);

apps/nextjs/src/components/assistant/assistant-gate.tsx

@@ -34,15 +34,11 @@ const DisabledAssistant = ({ children, description }: PropsWithChildren<{ descri
       isRunning: false,
       isRefreshing: false,
       unreadCount: 0,
-      hasVisibleWidget: false,
-      activeWidgetId: null,
       open: () => undefined,
       close: () => undefined,
       toggle: () => undefined,
       sendPrompt: () => false,
       refreshCurrentView: () => Promise.resolve(),
-      setWidgetVisible: () => undefined,
-      activateWidget: () => undefined,
     }),
     [description],
   );

apps/nextjs/src/components/assistant/assistant-human-tools.tsx

@@ -29,7 +29,7 @@ import { AppForm } from "@homarr/forms-collection";
 import { useScopedI18n } from "@homarr/translation/client";
 import type { appManageSchema } from "@homarr/validation/app";
 
-import { getAssistantAskUserOptionKind } from "./assistant-ask-user";
+import { getAssistantAffirmativeResult, getAssistantAskUserOptionKind } from "./assistant-ask-user";
 import { useAssistantAutomaticAction } from "./assistant-auto-approval";
 import { AssistantAutomaticActionProgress } from "./assistant-automatic-action-progress";
 import classes from "./assistant-panel.module.css";
@@ -67,6 +67,7 @@ export const AssistantAskUserTool = ({
   result,
   addResult,
   status,
+  toolCallId,
 }: ToolCallMessagePartProps<AskUserArgs, AskUserResult>) => {
   const t = useScopedI18n("common.assistant.askUser");
   const [showOther, setShowOther] = useState(false);
@@ -74,6 +75,17 @@ export const AssistantAskUserTool = ({
   const [submitting, setSubmitting] = useState(false);
   const otherInputRef = useRef<HTMLInputElement>(null);
   const options = Array.isArray(args?.options) ? args.options : [];
+  const affirmativeResult = getAssistantAffirmativeResult(options);
+  const hasValidQuestion = hasCompleteAssistantToolArguments(status) && Boolean(args?.question) && options.length >= 2;
+  const autoConfirming = useAssistantAutomaticAction({
+    toolCallId,
+    ready: result === undefined && hasValidQuestion && affirmativeResult !== undefined,
+    completed: result !== undefined,
+    confirm: () => {
+      if (!affirmativeResult) return;
+      addResult(affirmativeResult);
+    },
+  });
 
   useEffect(() => {
     if (showOther) otherInputRef.current?.focus();
@@ -153,62 +165,67 @@ export const AssistantAskUserTool = ({
         </Group>
 
         <Stack gap="xs" mt="md">
-          {options.map((option, index) => {
-            const kind = getAssistantAskUserOptionKind(option);
-            const icon =
-              kind === "affirmative" ? (
-                <IconCheck size={17} />
-              ) : kind === "negative" ? (
-                <IconX size={17} />
-              ) : (
-                <IconArrowRight size={17} />
-              );
-            const color = kind === "affirmative" ? "green" : kind === "negative" ? "red" : "gray";
+          {autoConfirming ? (
+            <AssistantAutomaticActionProgress label={t("automaticAffirmative")} />
+          ) : (
+            options.map((option, index) => {
+              const kind = getAssistantAskUserOptionKind(option);
+              const icon =
+                kind === "affirmative" ? (
+                  <IconCheck size={17} />
+                ) : kind === "negative" ? (
+                  <IconX size={17} />
+                ) : (
+                  <IconArrowRight size={17} />
+                );
+              const color = kind === "affirmative" ? "green" : kind === "negative" ? "red" : "gray";
 
-            return (
-              <UnstyledButton
-                key={`${option.id}:${index}`}
-                className={classes.humanToolOption}
-                data-kind={kind}
-                disabled={submitting}
-                onClick={() =>
-                  submitResult({ answer: option.label, optionId: option.id, optionKind: kind, source: "option" })
-                }
-              >
-                <ThemeIcon className={classes.humanToolOptionIcon} variant="light" color={color} size="sm">
-                  {icon}
-                </ThemeIcon>
-                <Box className={classes.humanToolOptionText} ta="start">
-                  <Text component="span" size="sm" fw={650} className={classes.humanToolOptionLabel}>
-                    {option.label}
-                  </Text>
-                  {option.description && (
-                    <Text
-                      component="span"
-                      display="block"
-                      size="xs"
-                      c="dimmed"
-                      fw={400}
-                      className={classes.humanToolOptionDescription}
-                    >
-                      {option.description}
-                    </Text>
-                  )}
-                </Box>
-                <Badge
-                  className={classes.humanToolOptionBadge}
-                  classNames={{ label: classes.humanToolOptionBadgeLabel }}
-                  variant="light"
-                  color={color}
-                  size="xs"
+              return (
+                <UnstyledButton
+                  key={`${option.id}:${index}`}
+                  className={classes.humanToolOption}
+                  data-kind={kind}
+                  disabled={submitting}
+                  onClick={() =>
+                    submitResult({ answer: option.label, optionId: option.id, optionKind: kind, source: "option" })
+                  }
                 >
-                  {t(`optionKind.${kind}`)}
-                </Badge>
-              </UnstyledButton>
-            );
-          })}
+                  <ThemeIcon className={classes.humanToolOptionIcon} variant="light" color={color} size="sm">
+                    {icon}
+                  </ThemeIcon>
+                  <Box className={classes.humanToolOptionText} ta="start">
+                    <Text component="span" size="sm" fw={650} className={classes.humanToolOptionLabel}>
+                      {option.label}
+                    </Text>
+                    {option.description && (
+                      <Text
+                        component="span"
+                        display="block"
+                        size="xs"
+                        c="dimmed"
+                        fw={400}
+                        className={classes.humanToolOptionDescription}
+                      >
+                        {option.description}
+                      </Text>
+                    )}
+                  </Box>
+                  <Badge
+                    className={classes.humanToolOptionBadge}
+                    classNames={{ label: classes.humanToolOptionBadgeLabel }}
+                    variant="light"
+                    color={color}
+                    size="xs"
+                  >
+                    {t(`optionKind.${kind}`)}
+                  </Badge>
+                </UnstyledButton>
+              );
+            })
+          )}
 
-          {args.allowOther !== false &&
+          {!autoConfirming &&
+            args.allowOther !== false &&
             (showOther ? (
               <Group align="flex-end" gap="xs" wrap="nowrap">
                 <TextInput

apps/nextjs/src/components/assistant/assistant-panel.module.css

@@ -98,18 +98,18 @@
   container-type: size;
   position: fixed;
   z-index: 290;
-  inset-block: 1rem;
-  inset-inline-end: 1rem;
-  inset-inline-start: auto;
+  inset-inline-start: 50%;
+  bottom: 1rem;
   display: flex;
-  width: min(34rem, calc(100vw - 2rem));
-  height: auto;
-  min-height: min(30rem, calc(100dvh - 2rem));
+  width: min(46rem, calc(100vw - 2rem));
+  height: min(36rem, calc(100dvh - 5rem));
+  min-height: min(22rem, calc(100dvh - 5rem));
   margin: 0;
+  transform: translateX(-50%);
   flex-direction: column;
   overflow: hidden;
   padding: 0;
-  border: 1px solid var(--mantine-color-default-border);
+  border: 0;
   border-radius: var(--mantine-radius-lg);
   color: var(--mantine-color-text);
   background: var(--mantine-color-body);
@@ -157,28 +157,27 @@
   border-bottom: 1px solid var(--mantine-color-default-border);
 }
 
-.panelIdentity {
-  min-width: 0;
-  flex: 1 1 auto;
-}
-
-.panelIdentityIcon {
-  flex: 0 0 auto;
-}
-
-.panelIdentityTitle,
-.panelThreadTitle {
-  max-width: 14rem;
-}
-
 .panelActions {
   min-width: 0;
   flex: 0 0 auto;
   margin-inline-start: auto;
 }
 
-.newConversationButton {
+.windowControls {
   flex: 0 0 auto;
+  margin: 0;
+  padding: 0;
+  border: 0;
+}
+
+.windowControl {
+  width: 2.25rem;
+  height: 2.25rem;
+}
+
+.windowControl:focus-visible {
+  outline: 2px solid var(--mantine-primary-color-filled);
+  outline-offset: 2px;
 }
 
 .panelAction {
@@ -192,6 +191,10 @@
     padding: 0.45rem 0.5rem 0.45rem 0.65rem;
   }
 
+  .composerHints {
+    display: none;
+  }
+
   .historyButton {
     width: 2.625rem;
     max-width: 2.625rem;
@@ -207,21 +210,6 @@
     display: none;
   }
 
-  .newConversationButton {
-    width: 2.625rem;
-    max-width: 2.625rem;
-    height: 2.625rem;
-    padding-inline: 0.75rem;
-  }
-
-  .newConversationButton :global(.mantine-Button-section) {
-    margin-inline: 0;
-  }
-
-  .newConversationButton :global(.mantine-Button-label) {
-    display: none;
-  }
-
   .messages {
     padding: 0.5rem 0.65rem 1rem;
   }
@@ -258,27 +246,9 @@
   }
 }
 
-@container assistant-widget (max-width: 36rem) {
-  .historyButton {
-    width: 2.625rem;
-    max-width: 2.625rem;
-    height: 2.625rem;
-    padding-inline: 0.75rem;
-  }
-
-  .historyButtonSection {
-    margin-inline-end: 0;
-  }
-
-  .historyButtonLabel {
-    display: none;
-  }
-}
-
 @container assistant-widget (max-width: 22rem) {
   .panelAction,
-  .historyButton,
-  .newConversationButton {
+  .historyButton {
     width: 2.25rem;
     max-width: 2.25rem;
     height: 2.25rem;
@@ -298,11 +268,7 @@
     padding-inline: 0.15rem;
   }
 
-  .composerContextLabel {
-    display: none;
-  }
-
-  .panelThreadTitle {
+  .composerContext > :last-child {
     display: none;
   }
 }
@@ -332,70 +298,17 @@
 }
 
 .historyMenu {
-  min-width: 0;
-  overflow: hidden;
   background: var(--mantine-color-body);
 }
 
-.historyMenu :global(.mantine-ScrollArea-content) {
-  display: block;
-  width: 100%;
-  min-width: 0;
-}
-
 .historyItem {
-  display: flex;
-  width: 100%;
-  min-width: 0;
-  max-width: 100%;
-  box-sizing: border-box;
-  align-items: center;
-  gap: 0.2rem;
-  overflow: hidden;
-  padding: 0.15rem 0.2rem 0.15rem 0.35rem;
   border-radius: var(--mantine-radius-md);
 }
 
-.historyItem:hover,
-.historyItem[data-active] {
+.historyItem:hover {
   background: var(--mantine-color-default-hover);
 }
 
-.historyItemTrigger {
-  min-width: 0;
-  flex: 1;
-  overflow: hidden;
-  padding: 0.35rem 0.25rem;
-  text-align: start;
-}
-
-.historyItemTrigger > span {
-  display: block;
-  width: 100%;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-.historyRenameInput {
-  min-width: 0;
-  flex: 1;
-}
-
-.historyItemTrigger:focus-visible {
-  outline: 2px solid var(--mantine-primary-color-filled);
-  outline-offset: -1px;
-}
-
-.historyItemMenu {
-  flex: 0 0 auto;
-  opacity: 1;
-}
-
-.historyItemActions {
-  flex: 0 0 auto;
-}
-
 .thread {
   position: relative;
   display: flex;
@@ -428,11 +341,6 @@
   margin-block: 0.9rem;
 }
 
-.message[data-static] {
-  contain-intrinsic-size: auto 12rem;
-  content-visibility: auto;
-}
-
 .userMessageWrap {
   width: fit-content;
   max-width: 86%;
@@ -798,21 +706,24 @@
 
 .pendingQuestionDock {
   min-height: 0;
-  max-height: min(22rem, 48dvh);
-  flex: 0 1 auto;
+  flex: 1 1 auto;
   overflow-y: auto;
   overscroll-behavior: contain;
   padding: 0.75rem;
-  border-top: 1px solid var(--mantine-color-default-border);
   background: var(--mantine-color-body);
 }
 
+.thread[data-pending-question] .viewport {
+  display: none;
+}
+
 .pendingQuestionTarget {
   display: flex;
   width: 100%;
+  min-height: 100%;
   max-width: 44rem;
   margin-inline: auto;
-  align-items: flex-start;
+  align-items: safe center;
 }
 
 .pendingQuestionTarget .humanTool {
@@ -1180,43 +1091,6 @@
   flex: 0 1 auto;
 }
 
-.messageMoreMenu {
-  z-index: 410;
-  min-width: 11rem;
-  padding: 0.25rem;
-  border: 1px solid var(--mantine-color-default-border);
-  border-radius: var(--mantine-radius-md);
-  color: var(--mantine-color-text);
-  background: var(--mantine-color-body);
-  box-shadow: var(--mantine-shadow-md);
-}
-
-.messageMoreItem {
-  display: flex;
-  align-items: center;
-  gap: 0.5rem;
-  padding: 0.45rem 0.55rem;
-  border-radius: var(--mantine-radius-sm);
-  font-size: var(--mantine-font-size-sm);
-  cursor: pointer;
-  outline: 0;
-}
-
-.messageMoreItem[data-highlighted] {
-  background: var(--mantine-color-default-hover);
-}
-
-.messageMoreItem:focus-visible {
-  outline: 2px solid var(--mantine-primary-color-filled);
-  outline-offset: -2px;
-}
-
-.messageMoreSeparator {
-  height: 1px;
-  margin-block: 0.2rem;
-  background: var(--mantine-color-default-border);
-}
-
 .userActions {
   min-height: 1.75rem;
 }
@@ -1299,13 +1173,13 @@
 
 .composerContext {
   display: flex;
-  width: auto;
+  width: 1.75rem;
   height: 1.75rem;
   align-items: center;
   justify-content: center;
-  padding-inline: 0.3rem 0.42rem;
+  padding: 0;
   border: 1px solid var(--mantine-color-default-border);
-  border-radius: var(--mantine-radius-sm);
+  border-radius: 50%;
   color: var(--mantine-color-text);
   background: var(--mantine-color-body);
 }
@@ -1541,6 +1415,10 @@
   pointer-events: none;
 }
 
+.composerHints {
+  padding-inline: 0.45rem;
+}
+
 .composerFooter {
   min-width: 0;
   max-width: 100%;
@@ -1763,12 +1641,12 @@
 @keyframes assistant-panel-in {
   from {
     opacity: 0;
-    transform: translateY(0.75rem) scale(0.985);
+    transform: translate(-50%, 0.75rem) scale(0.985);
   }
 
   to {
     opacity: 1;
-    transform: translateY(0) scale(1);
+    transform: translate(-50%, 0) scale(1);
   }
 }
 
@@ -1778,11 +1656,10 @@
   }
 
   .floatingPanel {
-    inset: 0;
-    width: 100vw;
-    height: 100dvh;
-    min-height: 100dvh;
-    border-radius: 0;
+    bottom: max(0.5rem, env(safe-area-inset-bottom, 0px));
+    width: calc(100vw - 1rem);
+    height: min(44rem, calc(100dvh - 1rem - env(safe-area-inset-bottom, 0px)));
+    min-height: min(20rem, calc(100dvh - 1rem - env(safe-area-inset-bottom, 0px)));
   }
 
   .panelHeader {
@@ -1809,6 +1686,10 @@
     padding-inline: 0.1rem;
   }
 
+  .composerHints {
+    display: none;
+  }
+
   .runtimeSelectorTrigger {
     max-width: 100%;
   }
@@ -1824,10 +1705,6 @@
 }
 
 @media (max-width: 30em) {
-  .historyItemMenu {
-    opacity: 1;
-  }
-
   .historyButton {
     width: 2.625rem;
     max-width: 2.625rem;

apps/nextjs/src/components/assistant/assistant-panel.tsx

@@ -25,8 +25,6 @@ import type {
 import type { MessageStatus } from "@assistant-ui/react";
 import {
   ActionBarPrimitive,
-  ActionBarMorePrimitive,
-  AuiIf,
   AttachmentPrimitive,
   BranchPickerPrimitive,
   ChainOfThoughtByIndicesProvider,
@@ -68,7 +66,6 @@ import {
   SegmentedControl,
   Stack,
   Text,
-  TextInput,
   ThemeIcon,
   Tooltip,
   UnstyledButton,
@@ -94,7 +91,6 @@ import {
   IconChevronUp,
   IconCopy,
   IconDownload,
-  IconDotsVertical,
   IconFile,
   IconFileExport,
   IconLink,
@@ -116,8 +112,6 @@ import {
   IconThumbUp,
   IconTool,
   IconTrash,
-  IconVolume,
-  IconVolumeOff,
   IconX,
 } from "@tabler/icons-react";
 import remarkBreaks from "remark-breaks";
@@ -130,7 +124,6 @@ import { useTimeAgo } from "@homarr/common";
 import { assistantProviderIds, assistantProviderPresets, assistantReasoningModes } from "@homarr/definitions";
 import type { AssistantProvider } from "@homarr/definitions";
 import { showErrorNotification, showSuccessNotification } from "@homarr/notifications";
-import { useConfirmModal } from "@homarr/modals";
 import { useCurrentIntlLocale, useScopedI18n } from "@homarr/translation/client";
 
 import classes from "./assistant-panel.module.css";
@@ -191,7 +184,6 @@ interface AssistantPanelProps extends AssistantConversationControls {
   onClose: () => void;
   onDismissActivity: () => void;
   activityDismissed: boolean;
-  hasVisibleWidget: boolean;
   isRunning: boolean;
   unreadCount: number;
   latestAssistantText: string;
@@ -1115,43 +1107,63 @@ const downloadAssistantMarkdown = (markdown: string, filename: string) => {
   setTimeout(() => URL.revokeObjectURL(blobUrl), 0);
 };
 
-const AssistantMessageActions = () => {
+const AssistantMessageExportAction = () => {
   const t = useScopedI18n("common.assistant");
-  const aui = useAui();
-  const exportMessage = () => {
-    const message = aui.message().getState();
-    const markdown = buildAssistantMessageMarkdown({
-      id: message.id,
-      parentId: message.parentId,
-      format: "assistant-ui/runtime",
-      content: message,
-      createdAt: message.createdAt,
-    });
-    downloadAssistantMarkdown(markdown, `assistant-message-${message.id.slice(0, 8)}.md`);
-  };
+  const message = useAuiState((state) => state.message);
 
   return (
-    <Box className={classes.messageActions}>
-      <ActionBarPrimitive.Root
-        hideWhenRunning
-        autohide="not-last"
-        autohideFloat="single-branch"
-        className={classes.messageActionBar}
+    <Tooltip label={t("exportMarkdown")}>
+      <ActionIcon
+        variant="subtle"
+        color="gray"
+        size="sm"
+        aria-label={t("exportMarkdown")}
+        onClick={() => {
+          const markdown = buildAssistantMessageMarkdown({
+            id: message.id,
+            parentId: message.parentId,
+            format: "assistant-ui/runtime",
+            content: message,
+            createdAt: message.createdAt,
+          });
+          downloadAssistantMarkdown(markdown, `assistant-message-${message.id.slice(0, 8)}.md`);
+        }}
       >
-        <Group gap={2} wrap="nowrap">
+        <IconFileExport size={14} />
+      </ActionIcon>
+    </Tooltip>
+  );
+};
+
+const AssistantMessageActions = () => {
+  const t = useScopedI18n("common.assistant");
+  return (
+    <Box className={classes.messageActions}>
+      <ActionBarPrimitive.Root hideWhenRunning className={classes.messageActionBar}>
+        <Group gap={2} wrap="wrap">
           <ProviderMessageInfo />
           <Tooltip label={t("copy")}>
             <ActionBarPrimitive.Copy asChild>
               <ActionIcon variant="subtle" color="gray" size="sm" aria-label={t("copy")}>
-                <AuiIf condition={(state) => !state.message.isCopied}>
-                  <IconCopy size={14} />
-                </AuiIf>
-                <AuiIf condition={(state) => state.message.isCopied}>
-                  <IconCheck size={14} />
-                </AuiIf>
+                <IconCopy size={14} />
               </ActionIcon>
             </ActionBarPrimitive.Copy>
           </Tooltip>
+          <Tooltip label={t("helpful")}>
+            <ActionBarPrimitive.FeedbackPositive asChild>
+              <ActionIcon variant="subtle" color="gray" size="sm" aria-label={t("helpful")}>
+                <IconThumbUp size={14} />
+              </ActionIcon>
+            </ActionBarPrimitive.FeedbackPositive>
+          </Tooltip>
+          <Tooltip label={t("notHelpful")}>
+            <ActionBarPrimitive.FeedbackNegative asChild>
+              <ActionIcon variant="subtle" color="gray" size="sm" aria-label={t("notHelpful")}>
+                <IconThumbDown size={14} />
+              </ActionIcon>
+            </ActionBarPrimitive.FeedbackNegative>
+          </Tooltip>
+          <AssistantMessageExportAction />
           <Tooltip label={t("regenerate")}>
             <ActionBarPrimitive.Reload asChild>
               <ActionIcon variant="subtle" color="gray" size="sm" aria-label={t("regenerate")}>
@@ -1159,50 +1171,6 @@ const AssistantMessageActions = () => {
               </ActionIcon>
             </ActionBarPrimitive.Reload>
           </Tooltip>
-          <ActionBarMorePrimitive.Root>
-            <ActionBarMorePrimitive.Trigger asChild>
-              <ActionIcon variant="subtle" color="gray" size="sm" aria-label={t("moreActions")}>
-                <IconDotsVertical size={14} />
-              </ActionIcon>
-            </ActionBarMorePrimitive.Trigger>
-            <ActionBarMorePrimitive.Content className={classes.messageMoreMenu} sideOffset={4} align="end">
-              <ActionBarPrimitive.FeedbackPositive asChild>
-                <ActionBarMorePrimitive.Item className={classes.messageMoreItem}>
-                  <IconThumbUp size={15} />
-                  {t("helpful")}
-                </ActionBarMorePrimitive.Item>
-              </ActionBarPrimitive.FeedbackPositive>
-              <ActionBarPrimitive.FeedbackNegative asChild>
-                <ActionBarMorePrimitive.Item className={classes.messageMoreItem}>
-                  <IconThumbDown size={15} />
-                  {t("notHelpful")}
-                </ActionBarMorePrimitive.Item>
-              </ActionBarPrimitive.FeedbackNegative>
-              <AuiIf condition={(state) => state.thread.capabilities.speech && state.message.speech === undefined}>
-                <ActionBarPrimitive.Speak asChild>
-                  <ActionBarMorePrimitive.Item className={classes.messageMoreItem}>
-                    <IconVolume size={15} />
-                    {t("readAloud")}
-                  </ActionBarMorePrimitive.Item>
-                </ActionBarPrimitive.Speak>
-              </AuiIf>
-              <AuiIf condition={(state) => state.message.speech !== undefined}>
-                <ActionBarPrimitive.StopSpeaking asChild>
-                  <ActionBarMorePrimitive.Item className={classes.messageMoreItem}>
-                    <IconVolumeOff size={15} />
-                    {t("stopReading")}
-                  </ActionBarMorePrimitive.Item>
-                </ActionBarPrimitive.StopSpeaking>
-              </AuiIf>
-              <ActionBarMorePrimitive.Separator className={classes.messageMoreSeparator} />
-              <ActionBarPrimitive.ExportMarkdown onExport={() => exportMessage()} asChild>
-                <ActionBarMorePrimitive.Item className={classes.messageMoreItem}>
-                  <IconFileExport size={15} />
-                  {t("exportMarkdown")}
-                </ActionBarMorePrimitive.Item>
-              </ActionBarPrimitive.ExportMarkdown>
-            </ActionBarMorePrimitive.Content>
-          </ActionBarMorePrimitive.Root>
         </Group>
       </ActionBarPrimitive.Root>
       <BranchPicker />
@@ -1213,7 +1181,7 @@ const AssistantMessageActions = () => {
 const UserMessageActions = () => {
   const t = useScopedI18n("common.assistant");
   return (
-    <ActionBarPrimitive.Root hideWhenRunning autohide="not-last" className={classes.userActions}>
+    <ActionBarPrimitive.Root hideWhenRunning className={classes.userActions}>
       <Group gap={2}>
         <Tooltip label={t("copyMessage")}>
           <ActionBarPrimitive.Copy asChild>
@@ -1257,7 +1225,7 @@ const UserMessage = () => {
   const isEditing = useAuiState((state) => state.composer.isEditing);
   if (isEditing) return <EditComposer />;
   return (
-    <MessagePrimitive.Root className={`${classes.message} ${classes.userMessageWrap}`} data-static>
+    <MessagePrimitive.Root className={`${classes.message} ${classes.userMessageWrap}`}>
       <Box className={classes.userMessage}>
         <MessagePrimitive.Quote>
           {(quote) => (
@@ -1764,17 +1732,12 @@ const ConversationContext = () => {
           aria-haspopup="dialog"
           onClick={() => setOpened((value) => !value)}
         >
-          <Group gap={5} wrap="nowrap">
-            <RingProgress
-              size={22}
-              thickness={3}
-              roundCaps
-              sections={hasContext ? [{ value: contextPercentage, color: getContextColor(contextPercentage) }] : []}
-            />
-            <Text className={classes.composerContextLabel} component="span" size="xs" fw={650}>
-              {hasContext ? `${contextPercentage}%` : t("mentions.context")}
-            </Text>
-          </Group>
+          <RingProgress
+            size={24}
+            thickness={3}
+            roundCaps
+            sections={hasContext ? [{ value: contextPercentage, color: getContextColor(contextPercentage) }] : []}
+          />
         </UnstyledButton>
       </Popover.Target>
       <Popover.Dropdown className={classes.conversationContextPopover}>
@@ -1939,80 +1902,60 @@ const WebSearchActivity = () => {
   );
 };
 
-const AssistantMessage = () => {
-  const isComplete = useAuiState((state) => state.message.status?.type === "complete");
-
-  return (
-    <MessagePrimitive.Root
-      className={`${classes.message} ${classes.assistantMessage}`}
-      data-static={isComplete || undefined}
-    >
-      <MessagePrimitive.GroupedParts groupBy={assistantMessageGroupBy} indicator="empty">
-        {({ part, children }) => {
-          switch (part.type) {
-            case "group-agent-trace": {
-              const startIndex = part.indices[0];
-              const endIndex = part.indices.at(-1);
-              if (startIndex === undefined || endIndex === undefined) return null;
-              return (
-                <ChainOfThoughtByIndicesProvider startIndex={startIndex} endIndex={endIndex}>
-                  <AssistantChainOfThought>{children}</AssistantChainOfThought>
-                </ChainOfThoughtByIndicesProvider>
-              );
-            }
-            case "group-reasoning":
-              return <>{children}</>;
-            case "group-tool":
-              return <AgentTraceToolGroup>{children}</AgentTraceToolGroup>;
-            case "indicator":
-              return <AssistantMessagePending status={{ type: "running" }} />;
-            case "text":
-              return <AssistantTextPart />;
-            case "reasoning":
-              return <ReasoningPart {...part} />;
-            case "tool-call":
-              return part.toolUI ?? <ToolPart {...part} />;
-            case "source":
-              return <SourcePart {...part} />;
-            case "file":
-              return <FilePart {...part} />;
-            case "image":
-              return <ImagePart {...part} />;
-            case "data":
-              return part.dataRendererUI;
-            default:
-              return null;
+const AssistantMessage = () => (
+  <MessagePrimitive.Root className={`${classes.message} ${classes.assistantMessage}`}>
+    <MessagePrimitive.GroupedParts groupBy={assistantMessageGroupBy} indicator="empty">
+      {({ part, children }) => {
+        switch (part.type) {
+          case "group-agent-trace": {
+            const startIndex = part.indices[0];
+            const endIndex = part.indices.at(-1);
+            if (startIndex === undefined || endIndex === undefined) return null;
+            return (
+              <ChainOfThoughtByIndicesProvider startIndex={startIndex} endIndex={endIndex}>
+                <AssistantChainOfThought>{children}</AssistantChainOfThought>
+              </ChainOfThoughtByIndicesProvider>
+            );
           }
-        }}
-      </MessagePrimitive.GroupedParts>
-      <RuntimeError />
-      <WebSearchActivity />
-      <AssistantMessageActions />
-    </MessagePrimitive.Root>
-  );
-};
-
-const assistantThreadMessageComponents = { UserMessage, AssistantMessage };
+          case "group-reasoning":
+            return <>{children}</>;
+          case "group-tool":
+            return <AgentTraceToolGroup>{children}</AgentTraceToolGroup>;
+          case "indicator":
+            return <AssistantMessagePending status={{ type: "running" }} />;
+          case "text":
+            return <AssistantTextPart />;
+          case "reasoning":
+            return <ReasoningPart {...part} />;
+          case "tool-call":
+            return part.toolUI ?? <ToolPart {...part} />;
+          case "source":
+            return <SourcePart {...part} />;
+          case "file":
+            return <FilePart {...part} />;
+          case "image":
+            return <ImagePart {...part} />;
+          case "data":
+            return part.dataRendererUI;
+          default:
+            return null;
+        }
+      }}
+    </MessagePrimitive.GroupedParts>
+    <RuntimeError />
+    <WebSearchActivity />
+    <AssistantMessageActions />
+  </MessagePrimitive.Root>
+);
 
 const HistorySelectContext = createContext<() => void>(() => undefined);
 
 const ThreadListItem = () => {
   const t = useScopedI18n("common.assistant");
-  const aui = useAui();
-  const { openConfirmModal } = useConfirmModal();
   const onSelect = useContext(HistorySelectContext);
   const remoteId = useAuiState((state) => state.threadListItem.remoteId);
   const title = useAuiState((state) => state.threadListItem.title);
   const [exporting, setExporting] = useState(false);
-  const [actionsOpened, setActionsOpened] = useState(false);
-  const [renameOpened, setRenameOpened] = useState(false);
-  const [renaming, setRenaming] = useState(false);
-  const [nextTitle, setNextTitle] = useState(title ?? "");
-  const renameInputRef = useRef<HTMLInputElement>(null);
-
-  useEffect(() => {
-    if (renameOpened) renameInputRef.current?.focus();
-  }, [renameOpened]);
 
   const exportConversation = async () => {
     if (!remoteId || exporting) return;
@@ -2034,109 +1977,23 @@ const ThreadListItem = () => {
     }
   };
 
-  const renameConversation = async () => {
-    const trimmedTitle = nextTitle.trim();
-    if (!trimmedTitle || renaming) return;
-    setRenaming(true);
-    try {
-      await aui.threadListItem().rename(trimmedTitle);
-      setRenameOpened(false);
-      setActionsOpened(false);
-    } catch {
-      showErrorNotification({
-        title: t("renameConversation.failedTitle"),
-        message: t("renameConversation.failedDescription"),
-      });
-    } finally {
-      setRenaming(false);
-    }
-  };
-
-  const deleteConversation = () => {
-    openConfirmModal({
-      title: t("deleteConversation.title"),
-      children: t("deleteConversation.description", { title: title ?? t("newConversation") }),
-      confirmProps: { color: "red" },
-      labels: { confirm: t("delete"), cancel: t("cancel") },
-      onConfirm: async () => {
-        try {
-          await aui.threadListItem().delete();
-        } catch {
-          showErrorNotification({
-            title: t("deleteConversation.failedTitle"),
-            message: t("deleteConversation.failedDescription"),
-          });
-        }
-      },
-    });
-  };
-
-  if (renameOpened) {
-    return (
-      <ThreadListItemPrimitive.Root className={classes.historyItem}>
-        <TextInput
-          ref={renameInputRef}
-          className={classes.historyRenameInput}
-          value={nextTitle}
-          onChange={(event) => setNextTitle(event.currentTarget.value)}
-          aria-label={t("renameConversation.label")}
-          maxLength={72}
-          size="xs"
-          onKeyDown={(event) => {
-            if (event.key === "Enter") void renameConversation();
-            if (event.key === "Escape" && !renaming) setRenameOpened(false);
-          }}
-        />
-        <ActionIcon
-          variant="subtle"
-          color="green"
-          size="sm"
-          aria-label={t("renameConversation.save")}
-          disabled={!nextTitle.trim()}
-          loading={renaming}
-          loaderProps={{ type: "bars" }}
-          onClick={() => void renameConversation()}
-        >
-          <IconCheck size={15} />
-        </ActionIcon>
-        <ActionIcon
-          variant="subtle"
-          color="gray"
-          size="sm"
-          aria-label={t("cancel")}
-          disabled={renaming}
-          onClick={() => setRenameOpened(false)}
-        >
-          <IconX size={15} />
-        </ActionIcon>
-      </ThreadListItemPrimitive.Root>
-    );
-  }
-
   return (
     <ThreadListItemPrimitive.Root className={classes.historyItem}>
-      <ThreadListItemPrimitive.Trigger asChild>
-        <UnstyledButton className={classes.historyItemTrigger} title={title} onClick={onSelect}>
-          <Text component="span" size="sm" fw={500} truncate>
-            <ThreadListItemPrimitive.Title fallback={t("newConversation")} />
-          </Text>
-        </UnstyledButton>
-      </ThreadListItemPrimitive.Trigger>
-      {actionsOpened && (
-        <Group className={classes.historyItemActions} gap={1} wrap="nowrap">
-          <ActionIcon
+      <Group gap={4} wrap="nowrap">
+        <ThreadListItemPrimitive.Trigger asChild>
+          <Button
             variant="subtle"
             color="gray"
-            size="sm"
-            title={t("renameConversation.action")}
-            aria-label={t("renameConversation.action")}
-            onClick={() => {
-              setNextTitle(title ?? "");
-              setRenameOpened(true);
-            }}
+            size="compact-sm"
+            justify="flex-start"
+            flex={1}
+            style={{ minWidth: 0 }}
+            onClick={onSelect}
           >
-            <IconPencil size={14} />
-          </ActionIcon>
+            <ThreadListItemPrimitive.Title fallback={t("newConversation")} />
+          </Button>
+        </ThreadListItemPrimitive.Trigger>
+        <Tooltip label={t("exportConversation.action")}>
           <ActionIcon
             variant="subtle"
             color="gray"
@@ -2144,49 +2001,24 @@ const ThreadListItem = () => {
             loading={exporting}
             loaderProps={{ type: "bars" }}
             disabled={!remoteId}
-            title={t("exportConversation.action")}
             aria-label={t("exportConversation.action")}
             onClick={() => void exportConversation()}
           >
             <IconFileExport size={14} />
           </ActionIcon>
-          <ActionIcon
-            variant="subtle"
-            color="red"
-            size="sm"
-            title={t("delete")}
-            aria-label={t("delete")}
-            onClick={deleteConversation}
-          >
+        </Tooltip>
+        <ThreadListItemPrimitive.Delete asChild>
+          <ActionIcon variant="subtle" color="red" size="sm" aria-label={t("delete")}>
             <IconTrash size={14} />
           </ActionIcon>
-        </Group>
-      )}
-      <ActionIcon
-        className={classes.historyItemMenu}
-        variant="subtle"
-        color="gray"
-        size="sm"
-        title={t("conversationActions")}
-        aria-label={t("conversationActions")}
-        aria-expanded={actionsOpened}
-        onClick={() => setActionsOpened((current) => !current)}
-      >
-        {actionsOpened ? <IconX size={15} /> : <IconDotsVertical size={15} />}
-      </ActionIcon>
+        </ThreadListItemPrimitive.Delete>
+      </Group>
     </ThreadListItemPrimitive.Root>
   );
 };
 
 const ThreadHistory = ({ onSelect }: { onSelect: () => void }) => {
   const t = useScopedI18n("common.assistant");
-  const [query, setQuery] = useState("");
-  const normalizedQuery = query.trim().toLocaleLowerCase();
-  const threadItems = useAuiState((state) => state.threads.threadItems);
-  const hasMatchingConversation = threadItems.some((item) => {
-    const itemTitle = item.title ?? t("newConversation");
-    return itemTitle.toLocaleLowerCase().includes(normalizedQuery);
-  });
   return (
     <HistorySelectContext.Provider value={onSelect}>
       <Stack className={classes.historyMenu} gap="xs" p="xs">
@@ -2203,28 +2035,9 @@ const ThreadHistory = ({ onSelect }: { onSelect: () => void }) => {
             {t("conversations")}
           </Text>
         </Group>
-        <TextInput
-          value={query}
-          onChange={(event) => setQuery(event.currentTarget.value)}
-          leftSection={<IconSearch size={15} />}
-          placeholder={t("searchConversations")}
-          aria-label={t("searchConversations")}
-          size="xs"
-        />
-        <ScrollArea.Autosize mah="min(24rem, 55dvh)" type="auto" scrollbars="y" offsetScrollbars>
+        <ScrollArea.Autosize mah="min(24rem, 55dvh)" type="auto" offsetScrollbars>
           <Stack gap={3}>
-            <ThreadListPrimitive.Items>
-              {({ threadListItem }) => {
-                const itemTitle = threadListItem.title ?? t("newConversation");
-                if (normalizedQuery && !itemTitle.toLocaleLowerCase().includes(normalizedQuery)) return null;
-                return <ThreadListItem />;
-              }}
-            </ThreadListPrimitive.Items>
-            {normalizedQuery && !hasMatchingConversation && (
-              <Text size="xs" c="dimmed" ta="center" py="md">
-                {t("noMatchingConversations")}
-              </Text>
-            )}
+            <ThreadListPrimitive.Items components={{ ThreadListItem }} />
           </Stack>
         </ScrollArea.Autosize>
       </Stack>
@@ -2239,6 +2052,7 @@ const ConversationHistory = () => {
     <Popover
       opened={opened}
       onChange={setOpened}
+      onDismiss={() => setOpened(false)}
       position="bottom-end"
       width="min(22rem, calc(100vw - 1rem))"
       shadow="md"
@@ -2377,7 +2191,7 @@ const EmptyThread = () => {
             </Text>
           </Stack>
           <Box className={classes.suggestions}>
-            <ThreadPrimitive.Suggestion prompt={t("suggestions.health.prompt")} send={false} clearComposer asChild>
+            <ThreadPrimitive.Suggestion prompt={t("suggestions.health.prompt")} send asChild>
               <Button
                 variant="default"
                 className={classes.suggestion}
@@ -2386,17 +2200,17 @@ const EmptyThread = () => {
                 {t("suggestions.health.label")}
               </Button>
             </ThreadPrimitive.Suggestion>
-            <ThreadPrimitive.Suggestion prompt={t("suggestions.explore.prompt")} send={false} clearComposer asChild>
+            <ThreadPrimitive.Suggestion prompt={t("suggestions.explore.prompt")} send asChild>
               <Button variant="default" className={classes.suggestion} leftSection={<IconApps size={18} />}>
                 {t("suggestions.explore.label")}
               </Button>
             </ThreadPrimitive.Suggestion>
-            <ThreadPrimitive.Suggestion prompt={t("suggestions.media.prompt")} send={false} clearComposer asChild>
+            <ThreadPrimitive.Suggestion prompt={t("suggestions.media.prompt")} send asChild>
               <Button variant="default" className={classes.suggestion} leftSection={<IconSearch size={18} />}>
                 {t("suggestions.media.label")}
               </Button>
             </ThreadPrimitive.Suggestion>
-            <ThreadPrimitive.Suggestion prompt={t("suggestions.style.prompt")} send={false} clearComposer asChild>
+            <ThreadPrimitive.Suggestion prompt={t("suggestions.style.prompt")} send asChild>
               <Button variant="default" className={classes.suggestion} leftSection={<IconPalette size={18} />}>
                 {t("suggestions.style.label")}
               </Button>
@@ -2978,6 +2792,14 @@ const Composer = (props: ComposerProps) => {
                 <HomarrProviderQuota />
                 <ConversationContext />
               </Group>
+              <Group className={classes.composerHints} gap="xs" wrap="nowrap">
+                <Text size="xs" c="dimmed">
+                  {t("mentions.hint")}
+                </Text>
+                <Text size="xs" c="dimmed">
+                  {t("commands.hint")}
+                </Text>
+              </Group>
             </Group>
           </ComposerPrimitive.Root>
         </ComposerPrimitive.AttachmentDropzone>
@@ -3157,30 +2979,9 @@ interface AssistantConversationSurfaceProps extends AssistantConversationControl
   pendingAction: AssistantPendingAction | undefined;
   onExpand?: () => void;
   onMinimize?: () => void;
-  onDismiss?: () => void;
+  onWindowClose?: () => void;
 }
 
-const AssistantPanelIdentity = () => {
-  const t = useScopedI18n("common.assistant");
-  const threadTitle = useAuiState((state) => state.threadListItem.title);
-
-  return (
-    <Group className={classes.panelIdentity} gap="xs" wrap="nowrap">
-      <ThemeIcon className={classes.panelIdentityIcon} variant="light" color="red" radius="xl" size="md">
-        <IconRobot size={16} />
-      </ThemeIcon>
-      <Box miw={0}>
-        <Text className={classes.panelIdentityTitle} size="sm" fw={700} truncate>
-          {t("title")}
-        </Text>
-        <Text className={classes.panelThreadTitle} size="xs" c="dimmed" truncate>
-          {threadTitle ?? t("newConversation")}
-        </Text>
-      </Box>
-    </Group>
-  );
-};
-
 export const AssistantConversationSurface = ({
   isRunning,
   pendingAction,
@@ -3195,7 +2996,7 @@ export const AssistantConversationSurface = ({
   onReasoningChange,
   onExpand,
   onMinimize,
-  onDismiss,
+  onWindowClose,
 }: AssistantConversationSurfaceProps) => {
   const t = useScopedI18n("common.assistant");
   const reducedMotion = useReducedMotion();
@@ -3210,23 +3011,52 @@ export const AssistantConversationSurface = ({
   return (
     <AssistantDirectiveEntitiesProvider>
       <Group className={classes.panelHeader} justify="space-between" wrap="nowrap" gap="xs">
-        <AssistantPanelIdentity />
+        {onWindowClose && onMinimize && (
+          <Group
+            component="fieldset"
+            className={classes.windowControls}
+            gap={4}
+            wrap="nowrap"
+            aria-label={t("windowControls")}
+          >
+            <Tooltip label={t("close")}>
+              <ActionIcon
+                className={classes.windowControl}
+                variant="subtle"
+                color="gray"
+                onClick={onWindowClose}
+                aria-label={t("close")}
+              >
+                <IconX size={16} />
+              </ActionIcon>
+            </Tooltip>
+            <Tooltip label={t("minimize")}>
+              <ActionIcon
+                className={classes.windowControl}
+                variant="subtle"
+                color="gray"
+                onClick={onMinimize}
+                aria-label={t("minimize")}
+              >
+                <IconMinus size={17} />
+              </ActionIcon>
+            </Tooltip>
+          </Group>
+        )}
         <Group className={classes.panelActions} gap={2} wrap="nowrap">
           <ConversationHistory />
           <ViewRefreshAction isRefreshing={isRefreshing} onRefresh={onRefresh} />
           <AutoApprovalControl />
           <Tooltip label={t("newConversation")}>
             <ThreadListPrimitive.New asChild>
-              <Button
-                className={classes.newConversationButton}
+              <ActionIcon
+                className={classes.panelAction}
                 variant="subtle"
                 color="gray"
-                size="compact-sm"
-                leftSection={<IconPlus size={17} />}
                 aria-label={t("newConversation")}
               >
-                {t("newConversation")}
-              </Button>
+                <IconPlus size={17} />
+              </ActionIcon>
             </ThreadListPrimitive.New>
           </Tooltip>
           {onExpand && (
@@ -3242,32 +3072,6 @@ export const AssistantConversationSurface = ({
               </ActionIcon>
             </Tooltip>
           )}
-          {onMinimize && (
-            <Tooltip label={t("minimize")}>
-              <ActionIcon
-                className={classes.panelAction}
-                variant="subtle"
-                color="gray"
-                onClick={onMinimize}
-                aria-label={t("minimize")}
-              >
-                <IconMinus size={17} />
-              </ActionIcon>
-            </Tooltip>
-          )}
-          {onDismiss && (
-            <Tooltip label={t("close")}>
-              <ActionIcon
-                className={classes.panelAction}
-                variant="subtle"
-                color="gray"
-                onClick={onDismiss}
-                aria-label={t("close")}
-              >
-                <IconX size={16} />
-              </ActionIcon>
-            </Tooltip>
-          )}
         </Group>
       </Group>
       <AssistantQuestionPortalProvider target={questionPortalTarget}>
@@ -3279,7 +3083,7 @@ export const AssistantConversationSurface = ({
             <ThreadPrimitive.Viewport className={classes.viewport} autoScroll>
               <Box className={classes.messages}>
                 <EmptyThread />
-                <ThreadPrimitive.Messages components={assistantThreadMessageComponents} />
+                <ThreadPrimitive.Messages components={{ UserMessage, AssistantMessage }} />
               </Box>
               <SelectionToolbarPrimitive.Root className={classes.selectionToolbar}>
                 <SelectionToolbarPrimitive.Quote asChild>
@@ -3326,7 +3130,6 @@ export const AssistantPanel = ({
   onClose,
   onDismissActivity,
   activityDismissed,
-  hasVisibleWidget,
   isRunning,
   unreadCount,
   latestAssistantText,
@@ -3344,18 +3147,8 @@ export const AssistantPanel = ({
   onReasoningChange,
 }: AssistantPanelProps) => {
   const t = useScopedI18n("common.assistant");
-  const aui = useAui();
   const previousFocusRef = useRef<HTMLElement | null>(null);
   const panelRef = useRef<HTMLDialogElement>(null);
-  const stopSpeechWithoutSurface = () => {
-    if (hasVisibleWidget) return;
-    const thread = aui.thread();
-    if (thread.getState().speech !== undefined) thread.stopSpeaking();
-  };
-  const minimize = () => {
-    stopSpeechWithoutSurface();
-    onClose();
-  };
 
   useWindowEvent("keydown", (event) => {
     if (
@@ -3367,7 +3160,7 @@ export const AssistantPanel = ({
     )
       return;
     event.preventDefault();
-    minimize();
+    onClose();
   });
   useEffect(() => {
     if (!opened) {
@@ -3389,7 +3182,7 @@ export const AssistantPanel = ({
 
   return (
     <>
-      {!opened && !hasVisibleWidget && (
+      {!opened && (
         <AssistantActivityBar
           onOpen={onOpen}
           onDismissActivity={onDismissActivity}
@@ -3417,9 +3210,8 @@ export const AssistantPanel = ({
             onModelChange={onModelChange}
             onReasoningChange={onReasoningChange}
             autoFocusComposer
-            onMinimize={minimize}
-            onDismiss={() => {
-              stopSpeechWithoutSurface();
+            onMinimize={onClose}
+            onWindowClose={() => {
               onDismissActivity();
               onClose();
             }}

apps/nextjs/src/components/assistant/assistant-provider.tsx

@@ -7,19 +7,11 @@ import type {
   AttachmentAdapter,
   MessageFormatAdapter,
   RemoteThreadListAdapter,
-  SpeechSynthesisAdapter,
   ThreadHistoryAdapter,
   ThreadMessage,
   Toolkit,
 } from "@assistant-ui/react";
-import {
-  defineToolkit,
-  useAui,
-  useAuiEvent,
-  useAuiState,
-  useRemoteThreadListRuntime,
-  WebSpeechSynthesisAdapter,
-} from "@assistant-ui/react";
+import { defineToolkit, useAui, useAuiEvent, useAuiState, useRemoteThreadListRuntime } from "@assistant-ui/react";
 import { useChat } from "@ai-sdk/react";
 import { AssistantChatTransport, useAISDKRuntime } from "@assistant-ui/react-ai-sdk";
 import { useHotkeys } from "@mantine/hooks";
@@ -49,8 +41,7 @@ import type { AssistantReasoningMode, AssistantRuntimeModelOption } from "./assi
 import { resolveAssistantPreferenceModelId, resolveAssistantThreadPreferenceModelId } from "./assistant-preferences";
 import { assistantAiSdkRuntimeOptions } from "./assistant-runtime-options";
 import {
-  AssistantComposerRuntimeProvider,
-  AssistantComposerSurfaceBoundary,
+  AssistantComposerSurfaceProvider,
   AssistantRunFocusPreserver,
   AssistantRuntimeProviderWithTools,
 } from "./assistant-runtime-provider";
@@ -484,12 +475,6 @@ const AssistantThreadRuntime = () => {
       ),
     [selectedModel],
   );
-  const [speech, setSpeech] = useState<SpeechSynthesisAdapter>();
-  useEffect(() => {
-    if ("speechSynthesis" in window && typeof SpeechSynthesisUtterance !== "undefined") {
-      setSpeech(new WebSpeechSynthesisAdapter());
-    }
-  }, []);
   const feedback = useMemo(
     () => ({
       submit: ({ message, type }: { message: ThreadMessage; type: "positive" | "negative" }) => {
@@ -527,7 +512,6 @@ const AssistantThreadRuntime = () => {
       history,
       attachments,
       feedback,
-      speech,
     },
   });
   transport.setRuntime(runtime);
@@ -683,7 +667,6 @@ const EnabledAssistantProvider = ({ children }: PropsWithChildren) => {
   const [opened, setOpened] = useState(false);
   const [activityDismissed, setActivityDismissed] = useState(true);
   const [unreadCount, setUnreadCount] = useState(0);
-  const [visibleWidgetIds, setVisibleWidgetIds] = useState<Set<string>>(() => new Set());
   const [queuedPrompt, setQueuedPrompt] = useState<string | null>(null);
   const aui = useAui();
   const preferences = useAssistantPreferences();
@@ -731,21 +714,6 @@ const EnabledAssistantProvider = ({ children }: PropsWithChildren) => {
     setOpened(true);
   }, [markRead]);
   const close = useCallback(() => setOpened(false), []);
-  const setWidgetVisible = useCallback((widgetId: string, visible: boolean) => {
-    setVisibleWidgetIds((current) => {
-      if (current.has(widgetId) === visible) return current;
-      const next = new Set(current);
-      if (visible) next.add(widgetId);
-      else next.delete(widgetId);
-      return next;
-    });
-  }, []);
-  const activateWidget = useCallback((widgetId: string) => {
-    setVisibleWidgetIds((current) => {
-      if (!current.has(widgetId) || current.values().next().value === widgetId) return current;
-      return new Set([widgetId, ...Array.from(current).filter((id) => id !== widgetId)]);
-    });
-  }, []);
   const toggle = useCallback(() => {
     if (opened) close();
     else open();
@@ -867,7 +835,6 @@ const EnabledAssistantProvider = ({ children }: PropsWithChildren) => {
   }, [assistantIsRunning, latestStatus?.type, providerUnavailable, sendPrompt, t]);
   useRegisterSpotlightContextResults("homarr-assistant", [spotlightItem], [spotlightItem]);
 
-  const activeWidgetId = visibleWidgetIds.values().next().value ?? null;
   const value = useMemo(
     () => ({
       enabled: true,
@@ -876,67 +843,46 @@ const EnabledAssistantProvider = ({ children }: PropsWithChildren) => {
       isRunning: assistantIsRunning,
       isRefreshing,
       unreadCount,
-      hasVisibleWidget: visibleWidgetIds.size > 0,
-      activeWidgetId,
       open,
       close,
       toggle,
       sendPrompt,
       refreshCurrentView,
-      setWidgetVisible,
-      activateWidget,
     }),
-    [
-      assistantIsRunning,
-      activateWidget,
-      activeWidgetId,
-      close,
-      isRefreshing,
-      open,
-      opened,
-      refreshCurrentView,
-      sendPrompt,
-      setWidgetVisible,
-      toggle,
-      unreadCount,
-      visibleWidgetIds.size,
-    ],
+    [assistantIsRunning, close, isRefreshing, open, opened, refreshCurrentView, sendPrompt, toggle, unreadCount],
   );
 
   return (
     <AssistantAutoApprovalProvider conversationId={conversationId}>
       <AssistantContext.Provider value={value}>
-        <AssistantComposerRuntimeProvider>
-          <AssistantWidgetRendererProvider renderer={AssistantBoardWidget}>{children}</AssistantWidgetRendererProvider>
-          <AssistantComposerSurfaceBoundary surfaceId="assistant-panel">
-            <AssistantPanel
-              opened={opened}
-              onOpen={open}
-              onClose={close}
-              onDismissActivity={() => {
-                markRead();
-                setActivityDismissed(true);
-              }}
-              activityDismissed={activityDismissed}
-              hasVisibleWidget={visibleWidgetIds.size > 0}
-              isRunning={assistantIsRunning}
-              unreadCount={unreadCount}
-              latestAssistantText={latestAssistantText}
-              latestAssistantPartType={latestAssistantPartType}
-              latestUserText={queuedPrompt ?? latestUserText}
-              latestStatus={latestStatus}
-              pendingAction={pendingAction}
-              modelId={preferences.modelId}
-              models={preferences.models}
-              modelOptionsLoading={preferences.isLoading}
-              reasoning={preferences.reasoning}
-              isRefreshing={isRefreshing}
-              onRefresh={refreshCurrentView}
-              onModelChange={selectModel}
-              onReasoningChange={preferences.setReasoning}
-            />
-          </AssistantComposerSurfaceBoundary>
-        </AssistantComposerRuntimeProvider>
+        <AssistantWidgetRendererProvider renderer={AssistantBoardWidget}>{children}</AssistantWidgetRendererProvider>
+        <AssistantComposerSurfaceProvider surfaceId="floating-panel">
+          <AssistantPanel
+            opened={opened}
+            onOpen={open}
+            onClose={close}
+            onDismissActivity={() => {
+              markRead();
+              setActivityDismissed(true);
+            }}
+            activityDismissed={activityDismissed}
+            isRunning={assistantIsRunning}
+            unreadCount={unreadCount}
+            latestAssistantText={latestAssistantText}
+            latestAssistantPartType={latestAssistantPartType}
+            latestUserText={queuedPrompt ?? latestUserText}
+            latestStatus={latestStatus}
+            pendingAction={pendingAction}
+            modelId={preferences.modelId}
+            models={preferences.models}
+            modelOptionsLoading={preferences.isLoading}
+            reasoning={preferences.reasoning}
+            isRefreshing={isRefreshing}
+            onRefresh={refreshCurrentView}
+            onModelChange={selectModel}
+            onReasoningChange={preferences.setReasoning}
+          />
+        </AssistantComposerSurfaceProvider>
       </AssistantContext.Provider>
     </AssistantAutoApprovalProvider>
   );

apps/nextjs/src/components/assistant/assistant-runtime-provider.spec.ts

@@ -26,8 +26,7 @@ import { z } from "zod/v4";
 import { showErrorNotification } from "@homarr/notifications";
 
 import {
-  AssistantComposerRuntimeProvider,
-  AssistantComposerSurfaceBoundary,
+  AssistantComposerSurfaceProvider,
   AssistantRunFocusPreserver,
   AssistantRuntimeProviderWithTools,
   assistantSurfaceComposerCacheLimit,
@@ -149,22 +148,14 @@ const SurfaceTestAssistant = ({
     { runtime, toolkit },
     createElement(AssistantRunFocusPreserver),
     createElement(
-      AssistantComposerRuntimeProvider,
-      null,
-      createElement(
-        AssistantComposerSurfaceBoundary,
-        { surfaceId: "surface-a" },
-        createElement(SurfaceProbe, { id: "a", onReady }),
-      ),
+      AssistantComposerSurfaceProvider,
+      { surfaceId: "surface-a" },
+      createElement(SurfaceProbe, { id: "a", onReady }),
     ),
     createElement(
-      AssistantComposerRuntimeProvider,
-      null,
-      createElement(
-        AssistantComposerSurfaceBoundary,
-        { surfaceId: "surface-b" },
-        createElement(SurfaceProbe, { id: "b", onReady }),
-      ),
+      AssistantComposerSurfaceProvider,
+      { surfaceId: "surface-b" },
+      createElement(SurfaceProbe, { id: "b", onReady }),
     ),
     simulateRunFocus ? createElement(LexicalRunFocusProbe) : null,
   );

apps/nextjs/src/components/assistant/assistant-runtime-provider.tsx

@@ -157,6 +157,9 @@ const createSurfaceComposerHost = (
     get attachments() {
       return getThreadAdapters(threadCore)?.attachments ? attachments : undefined;
     },
+    get dictation() {
+      return getThreadAdapters(threadCore)?.dictation;
+    },
   };
 
   return new Proxy(threadCore as ThreadCoreWithAdapters, {
@@ -291,21 +294,18 @@ export const createAssistantSurfaceRuntime = (runtime: AssistantRuntime): Assist
     subscribe(callback) {
       let activeCore = sharedBinding.getState();
       let activeConversationId = getConversationId();
-      let activeComposer = getComposer(activeConversationId, activeCore);
       retainConversation(activeConversationId);
-      let unsubscribeComposer = activeComposer.subscribe(callback);
+      let unsubscribeComposer = getComposer(activeConversationId, activeCore).subscribe(callback);
       const handleSharedUpdate = () => {
         const nextCore = sharedBinding.getState();
         const nextConversationId = getConversationId();
         if (nextCore !== activeCore || nextConversationId !== activeConversationId) {
-          if (activeCore.speech !== undefined) activeCore.stopSpeaking();
           unsubscribeComposer();
           releaseConversation(activeConversationId);
           activeCore = nextCore;
           activeConversationId = nextConversationId;
           retainConversation(activeConversationId);
-          activeComposer = getComposer(activeConversationId, activeCore);
-          unsubscribeComposer = activeComposer.subscribe(callback);
+          unsubscribeComposer = getComposer(activeConversationId, activeCore).subscribe(callback);
         }
         callback();
       };
@@ -360,13 +360,6 @@ export const createAssistantSurfaceRuntime = (runtime: AssistantRuntime): Assist
     registerModelContextProvider: () => () => {},
     dispose() {
       activeConversationCounts.clear();
-      const threadCores = new Set([
-        ...Array.from(surfaceCoreByConversation.values(), (entry) => entry.source),
-        ...Array.from(composerByConversation.values(), (entry) => entry.source),
-      ]);
-      for (const threadCore of threadCores) {
-        if (threadCore.speech !== undefined) threadCore.stopSpeaking();
-      }
       for (const [conversationId, entry] of composerByConversation) disposeComposer(conversationId, entry);
     },
   };
@@ -380,7 +373,7 @@ const AssistantComposerSurfaceContext = createContext<AssistantComposerSurfaceVa
 
 export const useAssistantComposerSurface = () => {
   const value = useContext(AssistantComposerSurfaceContext);
-  if (!value) throw new Error("useAssistantComposerSurface must be used within AssistantComposerSurfaceBoundary");
+  if (!value) throw new Error("useAssistantComposerSurface must be used within AssistantComposerSurfaceProvider");
   return value;
 };
 
@@ -444,23 +437,21 @@ const AssistantComposerSurfaceEvents = () => {
   return null;
 };
 
-export const AssistantComposerSurfaceBoundary = ({ children, surfaceId }: PropsWithChildren<{ surfaceId: string }>) => {
+const AssistantComposerSurfaceBoundary = ({ children, surfaceId }: PropsWithChildren<{ surfaceId: string }>) => {
   const t = useScopedI18n("common.assistant");
   const aui = useAui();
-  const instanceId = useId();
-  const resolvedSurfaceId = `${surfaceId}:${instanceId}`;
   const elementRef = useRef<HTMLDivElement>(null);
-  const contextValue = useMemo(() => ({ id: resolvedSurfaceId }), [resolvedSurfaceId]);
+  const contextValue = useMemo(() => ({ id: surfaceId }), [surfaceId]);
 
   useLayoutEffect(() => {
     const element = elementRef.current;
     if (!element) return undefined;
-    surfaceElements.set(resolvedSurfaceId, element);
+    surfaceElements.set(surfaceId, element);
 
     return () => {
-      if (surfaceElements.get(resolvedSurfaceId) === element) surfaceElements.delete(resolvedSurfaceId);
+      if (surfaceElements.get(surfaceId) === element) surfaceElements.delete(surfaceId);
     };
-  }, [resolvedSurfaceId]);
+  }, [surfaceId]);
 
   const handlePasteCapture = (event: ClipboardEvent<HTMLDivElement>) => {
     const target = event.target;
@@ -516,6 +507,7 @@ export const AssistantComposerSurfaceBoundary = ({ children, surfaceId }: PropsW
         }}
         onPasteCapture={handlePasteCapture}
       >
+        <AssistantComposerSurfaceEvents />
         {children}
       </div>
     </AssistantComposerSurfaceContext.Provider>
@@ -574,12 +566,18 @@ export const AssistantRunFocusPreserver = () => {
   return null;
 };
 
+interface AssistantComposerSurfaceProviderProps extends PropsWithChildren {
+  surfaceId: string;
+}
+
 /**
- * Gives every rendered assistant surface one shared local composer while preserving the shared
- * conversation. Individual surfaces should add AssistantComposerSurfaceBoundary around their UI.
+ * Gives one rendered assistant surface a local composer while preserving the shared conversation.
+ * Every component below this boundary can keep using the normal assistant-ui primitives and hooks.
  */
-export const AssistantComposerRuntimeProvider = ({ children }: PropsWithChildren) => {
+export const AssistantComposerSurfaceProvider = ({ children, surfaceId }: AssistantComposerSurfaceProviderProps) => {
   const parentAui = useAui();
+  const instanceId = useId();
+  const resolvedSurfaceId = `${surfaceId}:${instanceId}`;
   // oxlint-disable-next-line no-underscore-dangle -- required to derive a scoped runtime without cloning the shared thread.
   const sharedRuntime = parentAui.threads().__internal_getAssistantRuntime?.();
   const surfaceRuntime = useMemo(() => {
@@ -590,8 +588,7 @@ export const AssistantComposerRuntimeProvider = ({ children }: PropsWithChildren
 
   return (
     <AssistantRuntimeProvider aui={parentAui} runtime={surfaceRuntime}>
-      <AssistantComposerSurfaceEvents />
-      {children}
+      <AssistantComposerSurfaceBoundary surfaceId={resolvedSurfaceId}>{children}</AssistantComposerSurfaceBoundary>
     </AssistantRuntimeProvider>
   );
 };

apps/nextjs/src/components/assistant/assistant-widget.tsx

@@ -1,9 +1,8 @@
 "use client";
 
 import type { CSSProperties, ReactNode } from "react";
-import { useEffect, useId, useRef } from "react";
 import { ActionIcon, Box, Center, Group, Stack, Text, ThemeIcon, Tooltip } from "@mantine/core";
-import { IconArrowsMaximize, IconArrowsMinimize, IconRobot } from "@tabler/icons-react";
+import { IconArrowsMaximize, IconRobot } from "@tabler/icons-react";
 import { useAui, useAuiState } from "@assistant-ui/react";
 
 import { useI18n } from "@homarr/translation/client";
@@ -14,47 +13,23 @@ import classes from "./assistant-panel.module.css";
 import { AssistantConversationSurface } from "./assistant-panel";
 import { getPendingAssistantAction } from "./assistant-pending-action";
 import { useAssistantPreferences, useHomarrAssistant } from "./assistant-context";
-import { AssistantComposerSurfaceBoundary } from "./assistant-runtime-provider";
+import { AssistantComposerSurfaceProvider } from "./assistant-runtime-provider";
 
 export const AssistantBoardWidget = (props: WidgetComponentProps<"assistant">) => {
   const assistant = useHomarrAssistant();
-  const { enabled, setWidgetVisible } = assistant;
-  const generatedWidgetId = useId();
-  const widgetId = props.itemId ?? generatedWidgetId;
-  const widgetRef = useRef<HTMLDivElement>(null);
-
-  useEffect(() => {
-    const widget = widgetRef.current;
-    if (!enabled || !widget) return;
-    const observer = new IntersectionObserver(([entry]) => setWidgetVisible(widgetId, entry?.isIntersecting === true), {
-      threshold: 0.15,
-    });
-    observer.observe(widget);
-    return () => {
-      observer.disconnect();
-      setWidgetVisible(widgetId, false);
-    };
-  }, [enabled, setWidgetVisible, widgetId]);
 
   if (!assistant.enabled) {
     return <UnavailableAssistantWidget description={assistant.unavailableDescription} />;
   }
 
   return (
-    <AssistantComposerSurfaceBoundary surfaceId={`assistant-widget-${widgetId}`}>
-      <Box ref={widgetRef} w="100%" h="100%">
-        <EnabledAssistantBoardWidget {...props} assistantWidgetId={widgetId} />
-      </Box>
-    </AssistantComposerSurfaceBoundary>
+    <AssistantComposerSurfaceProvider surfaceId={`board-widget-${props.itemId ?? "preview"}`}>
+      <EnabledAssistantBoardWidget {...props} />
+    </AssistantComposerSurfaceProvider>
   );
 };
 
-const EnabledAssistantBoardWidget = ({
-  width,
-  height,
-  isEditMode,
-  assistantWidgetId,
-}: WidgetComponentProps<"assistant"> & { assistantWidgetId: string }) => {
+const EnabledAssistantBoardWidget = ({ width, height, isEditMode }: WidgetComponentProps<"assistant">) => {
   const board = useRequiredBoard();
   const assistant = useHomarrAssistant();
   const preferences = useAssistantPreferences();
@@ -70,14 +45,6 @@ const EnabledAssistantBoardWidget = ({
     threadListItem.updateCustom({ ...threadListItem.getState().custom, modelId });
   };
 
-  if (assistant.opened) {
-    return <CompactAssistantWidget onOpen={assistant.close} location="panel" />;
-  }
-
-  if (assistant.activeWidgetId !== null && assistant.activeWidgetId !== assistantWidgetId) {
-    return <CompactAssistantWidget onOpen={() => assistant.activateWidget(assistantWidgetId)} location="widget" />;
-  }
-
   if (width < 300 || height < 280) {
     return <CompactAssistantWidget onOpen={assistant.open} />;
   }
@@ -108,30 +75,8 @@ const EnabledAssistantBoardWidget = ({
   );
 };
 
-const CompactAssistantWidget = ({
-  onOpen,
-  location = "compact",
-}: {
-  onOpen: () => void;
-  location?: "compact" | "panel" | "widget";
-}) => {
+const CompactAssistantWidget = ({ onOpen }: { onOpen: () => void }) => {
   const t = useI18n();
-  let title = t("widget.assistant.compact.title");
-  let description = t("widget.assistant.compact.description");
-  let actionLabel = t("widget.assistant.compact.open");
-  let actionIcon = <IconArrowsMaximize size={18} />;
-
-  if (location === "panel") {
-    title = t("widget.assistant.compact.openTitle");
-    description = t("widget.assistant.compact.openDescription");
-    actionLabel = t("widget.assistant.compact.returnToWidget");
-    actionIcon = <IconArrowsMinimize size={18} />;
-  }
-  if (location === "widget") {
-    title = t("widget.assistant.compact.otherWidgetTitle");
-    description = t("widget.assistant.compact.otherWidgetDescription");
-    actionLabel = t("widget.assistant.compact.useHere");
-  }
 
   return (
     <Box className={classes.widgetPanel}>
@@ -142,16 +87,23 @@ const CompactAssistantWidget = ({
           </ThemeIcon>
           <Stack className={classes.compactCopy} gap={1}>
             <Text className={classes.compactTitle} size="sm" fw={700} lineClamp={1}>
-              {title}
+              {t("widget.assistant.compact.title")}
             </Text>
             <Text className={classes.compactDescription} size="xs" c="dimmed" lineClamp={2}>
-              {description}
+              {t("widget.assistant.compact.description")}
             </Text>
           </Stack>
         </Group>
-        <Tooltip label={actionLabel}>
-          <ActionIcon variant="light" color="red" size={44} radius="md" onClick={onOpen} aria-label={actionLabel}>
-            {actionIcon}
+        <Tooltip label={t("widget.assistant.compact.open")}>
+          <ActionIcon
+            variant="light"
+            color="red"
+            size={44}
+            radius="md"
+            onClick={onOpen}
+            aria-label={t("widget.assistant.compact.open")}
+          >
+            <IconArrowsMaximize size={18} />
           </ActionIcon>
         </Tooltip>
       </Group>

apps/nextjs/src/components/board/items/item-content.tsx

@@ -227,7 +227,9 @@ const LoadedBoardItemContent = ({
     (host: HTMLDivElement | null) => {
       if (!host || !surfacePortalTarget || isAdvanced) return;
       cancelPreviewEntrance();
-      host.append(surfacePortalTarget);
+      if (host.childNodes.length !== 1 || host.firstChild !== surfacePortalTarget) {
+        host.replaceChildren(surfacePortalTarget);
+      }
     },
     [cancelPreviewEntrance, isAdvanced, surfacePortalTarget],
   );

packages/api/src/mcp.ts

@@ -12,6 +12,7 @@ import { iconsRouter } from "./router/icons";
 import { infoRouter } from "./router/info";
 import { integrationRouter } from "./router/integration/integration-router";
 import { inviteRouter } from "./router/invite";
+import { airQualityRouter } from "./router/widgets/air-quality";
 import { bazarrRouter } from "./router/widgets/bazarr";
 import { serverSettingsRouter } from "./router/serverSettings";
 import { beszelRouter } from "./router/widgets/beszel";
@@ -35,6 +36,7 @@ export const mcpRouter = createTRPCRouter({
   info: infoRouter,
   integration: integrationRouter,
   invite: inviteRouter,
+  airQuality: airQualityRouter,
   bazarr: bazarrRouter,
   serverSettings: serverSettingsRouter,
   beszel: beszelRouter,

packages/api/src/router/log.ts

@@ -11,10 +11,6 @@ import { createTRPCRouter, permissionRequiredProcedure } from "../trpc";
 
 const logger = createLogger({ module: "logRouter" });
 
-type LogSubscriptionEvent =
-  | { type: "history"; messages: LoggerMessage[] }
-  | { type: "message"; message: LoggerMessage };
-
 export const logRouter = createTRPCRouter({
   subscribe: permissionRequiredProcedure
     .requiresPermission("other-view-logs")
@@ -24,61 +20,15 @@ export const logRouter = createTRPCRouter({
       }),
     )
     .subscription(({ input }) => {
-      return observable<LogSubscriptionEvent>((emit) => {
-        let isClosed = false;
-        let unsubscribe: (() => void) | null = null;
-        let isHistoryLoaded = false;
-        const bufferedMessages: LoggerMessage[] = [];
-
-        const onMessage = (message: LoggerMessage) => {
-          if (!input.levels.includes(message.level)) return;
-
-          if (!isHistoryLoaded) {
-            bufferedMessages.push(message);
-            return;
-          }
-
-          emit.next({ type: "message", message });
-        };
-
-        void loggingChannel
-          .subscribeAsync(onMessage)
-          .then(async (unsubscribeFromLogging) => {
-            if (isClosed) {
-              unsubscribeFromLogging();
-              return;
-            }
-
-            unsubscribe = unsubscribeFromLogging;
-            logger.info("A tRPC client has connected to the logging procedure");
-
-            const history = (await loggingChannel.getRecentAsync()).filter((message) =>
-              input.levels.includes(message.level),
-            );
-            if (isClosed) return;
-
-            emit.next({ type: "history", messages: history });
-
-            const historyIds = new Set(history.map((message) => message.id));
-            isHistoryLoaded = true;
-            for (const message of bufferedMessages) {
-              if (!historyIds.has(message.id)) {
-                emit.next({ type: "message", message });
-              }
-            }
-            bufferedMessages.length = 0;
-          })
-          .catch((error: unknown) => {
-            unsubscribe?.();
-            unsubscribe = null;
-            if (!isClosed) {
-              emit.error(error);
-            }
-          });
+      return observable<LoggerMessage>((emit) => {
+        const unsubscribe = loggingChannel.subscribe((data) => {
+          if (!input.levels.includes(data.level)) return;
+          emit.next(data);
+        });
+        logger.info("A tRPC client has connected to the logging procedure");
 
         return () => {
-          isClosed = true;
-          unsubscribe?.();
+          unsubscribe();
         };
       });
     }),

packages/api/src/router/test/log.spec.ts

@@ -1,79 +0,0 @@
-import { describe, expect, test, vi } from "vitest";
-
-import type { Session } from "@homarr/auth";
-import type { LoggerMessage } from "@homarr/redis";
-
-import { logRouter } from "../log";
-
-const mocks = vi.hoisted(() => ({
-  getRecentAsync: vi.fn(),
-  subscribeAsync: vi.fn(),
-}));
-
-vi.mock("@homarr/redis", () => ({
-  loggingChannel: {
-    getRecentAsync: mocks.getRecentAsync,
-    subscribeAsync: mocks.subscribeAsync,
-  },
-}));
-
-const session = {
-  user: {
-    id: "log-viewer",
-    permissions: ["other-view-logs"],
-    colorScheme: "light",
-  },
-  expires: new Date(0).toISOString(),
-} satisfies Session;
-
-const createMessage = (id: string, timestamp: number): LoggerMessage => ({
-  id,
-  timestamp: new Date(timestamp),
-  level: "info",
-  message: id,
-});
-
-describe("log.subscribe", () => {
-  test("emits history before buffered live messages without duplicates", async () => {
-    const historyDeferred = Promise.withResolvers<LoggerMessage[]>();
-    let onMessage: ((message: LoggerMessage) => void) | undefined;
-    const unsubscribe = vi.fn();
-
-    mocks.subscribeAsync.mockImplementation(async (callback: (message: LoggerMessage) => void) => {
-      onMessage = callback;
-      return unsubscribe;
-    });
-    mocks.getRecentAsync.mockReturnValue(historyDeferred.promise);
-
-    const caller = logRouter.createCaller({
-      db: null as never,
-      deviceType: undefined,
-      session,
-    });
-    const subscription = await caller.subscribe({ levels: ["info"] });
-    const events: object[] = [];
-    const observer = subscription.subscribe({
-      next(event) {
-        events.push(event);
-      },
-    });
-
-    await vi.waitFor(() => expect(mocks.getRecentAsync).toHaveBeenCalledOnce());
-
-    const retainedMessage = createMessage("retained", 1);
-    const liveMessage = createMessage("live", 2);
-    onMessage?.(retainedMessage);
-    onMessage?.(liveMessage);
-    historyDeferred.resolve([retainedMessage]);
-
-    await vi.waitFor(() =>
-      expect(events).toEqual([
-        { type: "history", messages: [retainedMessage] },
-        { type: "message", message: liveMessage },
-      ]),
-    );
-
-    observer.unsubscribe();
-    expect(unsubscribe).toHaveBeenCalledOnce();
-  });
-});

packages/api/src/router/widgets/air-quality.ts

@@ -0,0 +1,29 @@
+import { z } from "zod/v4";
+
+import { env } from "@homarr/common/env";
+import { airQualityRequestHandler } from "@homarr/request-handler/air-quality";
+
+import { createTRPCRouter, publicProcedure } from "../../trpc";
+
+const atLocationInput = z.object({
+  longitude: z.number().min(-180).max(180),
+  latitude: z.number().min(-90).max(90),
+});
+
+export const airQualityRouter = createTRPCRouter({
+  atLocation: publicProcedure
+    .meta({
+      mcp: {
+        enabled: true,
+        description:
+          "Get current and forecast air quality, UV, pollutant, and pollen data for geographic coordinates. REQUIRED: latitude (-90 to 90) and longitude (-180 to 180).",
+      },
+    })
+    .input(atLocationInput)
+    .query(async ({ input }) => {
+      if (env.NO_EXTERNAL_CONNECTION) return null;
+
+      const handler = airQualityRequestHandler.handler(input);
+      return await handler.getDataAsync().then((result) => result.data);
+    }),
+});

packages/api/src/router/widgets/index.ts

@@ -13,6 +13,7 @@ export const widgetRouter = createTRPCRouter({
   bazarr: lazy(() => import("./bazarr").then((mod) => mod.bazarrRouter)),
   notebook: lazy(() => import("./notebook").then((mod) => mod.notebookRouter)),
   weather: lazy(() => import("./weather").then((mod) => mod.weatherRouter)),
+  airQuality: lazy(() => import("./air-quality").then((mod) => mod.airQualityRouter)),
   app: lazy(() => import("./app").then((mod) => mod.appRouter)),
   dnsHole: lazy(() => import("./dns-hole").then((mod) => mod.dnsHoleRouter)),
   smartHome: lazy(() => import("./smart-home").then((mod) => mod.smartHomeRouter)),

packages/api/src/router/widgets/weather.ts

@@ -6,8 +6,8 @@ import { weatherRequestHandler } from "@homarr/request-handler/weather";
 import { createTRPCRouter, publicProcedure } from "../../trpc";
 
 const atLocationInput = z.object({
-  longitude: z.number(),
-  latitude: z.number(),
+  longitude: z.number().min(-180).max(180),
+  latitude: z.number().min(-90).max(90),
 });
 
 export const weatherRouter = createTRPCRouter({

packages/api/src/test/mcp.spec.ts

@@ -9,6 +9,7 @@ vi.mock("@homarr/auth", () => ({}));
 
 const MCP_TOOL_ALLOWLIST = {
   query: [
+    "airQuality_atLocation",
     "apiKeys_getAll",
     "app_all",
     "app_byId",

packages/core/src/infrastructure/logs/constants.ts

@@ -1,20 +1,6 @@
-import z from "zod/v4";
-
 export const logLevels = ["error", "warn", "info", "debug"] as const;
 export type LogLevel = (typeof logLevels)[number];
 
-export const loggerMessageSchema = z.object({
-  id: z.string(),
-  timestamp: z.date(),
-  message: z.string(),
-  level: z.enum(logLevels),
-});
-export type LoggerMessage = z.infer<typeof loggerMessageSchema>;
-
-export const LOG_HISTORY_MAX_ENTRIES = 5_000;
-export const LOG_HISTORY_KEY = "list:logging:history";
-export const LOG_PUBLISH_CHANNEL = "pubSub:logging";
-
 export const logLevelConfiguration = {
   error: {
     prefix: "🔴",

packages/core/src/infrastructure/logs/transports/redis-transport.ts

@@ -1,11 +1,8 @@
-import { randomUUID } from "node:crypto";
-import { stringify } from "superjson";
+import superjson from "superjson";
 import Transport from "winston-transport";
 
 import type { RedisClient } from "../../redis/client";
 import { createRedisClient } from "../../redis/client";
-import type { LoggerMessage } from "../constants";
-import { LOG_HISTORY_KEY, LOG_HISTORY_MAX_ENTRIES, LOG_PUBLISH_CHANNEL } from "../constants";
 
 const messageSymbol = Symbol.for("message");
 const levelSymbol = Symbol.for("level");
@@ -16,41 +13,32 @@ const levelSymbol = Symbol.for("level");
 //
 export class RedisTransport extends Transport {
   private redis: RedisClient | null = null;
+  public static readonly publishChannel = "pubSub:logging";
 
   /**
-   * Retain the log in a bounded Redis list and publish it to live subscribers.
+   * Log the info to the Redis channel
    */
-  log(info: { [messageSymbol]: string; [levelSymbol]: LoggerMessage["level"] }, callback: () => void) {
+  log(info: { [messageSymbol]: string; [levelSymbol]: string }, callback: () => void) {
     setImmediate(() => {
       this.emit("logged", info);
     });
 
-    const message: LoggerMessage = {
-      id: randomUUID(),
-      timestamp: new Date(),
-      message: info[messageSymbol],
-      level: info[levelSymbol],
-    };
-    const serializedMessage = stringify(message);
+    // Is only initialized here because it did not work when initialized in the constructor or outside the class
+    this.redis ??= createRedisClient();
 
-    callback();
-
-    void Promise.resolve()
+    this.redis
+      .publish(
+        RedisTransport.publishChannel,
+        superjson.stringify({
+          message: info[messageSymbol],
+          level: info[levelSymbol],
+        }),
+      )
       .then(() => {
-        // Is only initialized here because it did not work when initialized in the constructor or outside the class
-        if (!this.redis) {
-          this.redis = createRedisClient();
-          this.redis.options.maxRetriesPerRequest = 1;
-          this.redis.on("error", () => undefined);
-        }
-
-        return this.redis
-          .multi()
-          .lpush(LOG_HISTORY_KEY, serializedMessage)
-          .ltrim(LOG_HISTORY_KEY, 0, LOG_HISTORY_MAX_ENTRIES - 1)
-          .publish(LOG_PUBLISH_CHANNEL, serializedMessage)
-          .exec();
+        callback();
       })
-      .catch(() => undefined);
+      .catch(() => {
+        // Ignore errors
+      });
   }
 }

packages/definitions/src/docs/homarr-docs-sitemap.ts

@@ -336,6 +336,10 @@ export type HomarrDocumentationPath =
   | "/docs/integrations/whats-up-docker"
   | "/docs/widgets/clock"
   | "/docs/widgets/weather"
+  | "/docs/widgets/today"
+  | "/docs/widgets/air-quality"
+  | "/docs/widgets/countdown"
+  | "/docs/widgets/timer"
   | "/docs/widgets/app"
   | "/docs/widgets/iframe"
   | "/docs/widgets/video"

packages/definitions/src/docs/widget-doc-slugs.ts

@@ -3,6 +3,10 @@ import type { WidgetKind } from "../widget";
 export const widgetDocSlugs: Record<WidgetKind, string | null> = {
   clock: "clock",
   weather: "weather",
+  today: "today",
+  airQuality: "air-quality",
+  countdown: "countdown",
+  timer: "timer",
   app: "app",
   iframe: "iframe",
   video: "video",

packages/definitions/src/widget.ts

@@ -1,6 +1,10 @@
 export const widgetKinds = [
   "clock",
   "weather",
+  "today",
+  "airQuality",
+  "countdown",
+  "timer",
   "app",
   "iframe",
   "video",
@@ -59,6 +63,10 @@ export const widgetKinds = [
 export type WidgetKind = (typeof widgetKinds)[number];
 
 export const widgetDefaultSizes: Partial<Record<WidgetKind, { width: number; height: number }>> = {
+  today: { width: 2, height: 1 },
+  airQuality: { width: 2, height: 1 },
+  countdown: { width: 2, height: 1 },
+  timer: { width: 2, height: 1 },
   uptimeKuma: { width: 2, height: 3 },
   audioStats: { width: 2, height: 2 },
   paperlessNgx: { width: 2, height: 2 },

packages/redis/src/index.ts

@@ -1,16 +1,6 @@
-import { parse } from "superjson";
-
-import type { LoggerMessage } from "@homarr/core/infrastructure/logs/constants";
-import {
-  loggerMessageSchema,
-  LOG_HISTORY_KEY,
-  LOG_HISTORY_MAX_ENTRIES,
-  LOG_PUBLISH_CHANNEL,
-} from "@homarr/core/infrastructure/logs/constants";
+import type { LogLevel } from "@homarr/core/infrastructure/logs/constants";
 
 import { createListChannel, createSubPubChannel } from "./lib/channel";
-import { ChannelSubscriptionTracker } from "./lib/channel-subscription-tracker";
-import { createRedisConnection } from "./lib/connection";
 
 export {
   handshakeAsync,
@@ -25,31 +15,9 @@ export const pingChannel = createSubPubChannel<
 >("ping");
 export const pingUrlChannel = createListChannel<string>("ping-url");
 
-export type { LoggerMessage } from "@homarr/core/infrastructure/logs/constants";
+export interface LoggerMessage {
+  message: string;
+  level: LogLevel;
+}
 
-const loggingHistoryClient = createRedisConnection();
-
-const parseLoggerMessage = (message: string): LoggerMessage | null => {
-  try {
-    const result = loggerMessageSchema.safeParse(parse<unknown>(message));
-    return result.success ? result.data : null;
-  } catch {
-    return null;
-  }
-};
-
-export const loggingChannel = {
-  subscribeAsync: (callback: (message: LoggerMessage) => void) =>
-    ChannelSubscriptionTracker.subscribeAsync(LOG_PUBLISH_CHANNEL, (message) => {
-      const parsedMessage = parseLoggerMessage(message);
-      if (parsedMessage) callback(parsedMessage);
-    }),
-  getRecentAsync: async () => {
-    const messages =
-      (await loggingHistoryClient?.lrange(LOG_HISTORY_KEY, 0, LOG_HISTORY_MAX_ENTRIES - 1).catch(() => [])) ?? [];
-    return messages
-      .map(parseLoggerMessage)
-      .filter((message): message is LoggerMessage => message !== null)
-      .toReversed();
-  },
-};
+export const loggingChannel = createSubPubChannel<LoggerMessage>("logging");

packages/redis/src/lib/channel-subscription-tracker.ts

@@ -18,7 +18,6 @@ type SubscriptionCallback = (message: string) => MaybePromise<void>;
  */
 export class ChannelSubscriptionTracker {
   private static subscriptions = new Map<string, Map<string, SubscriptionCallback>>();
-  private static subscriptionReadiness = new Map<string, Promise<void>>();
   private static redis = createRedisConnection();
   private static listenerActive = false;
 
@@ -29,25 +28,6 @@ export class ChannelSubscriptionTracker {
    * @returns a function to unsubscribe from the channel
    */
   public static subscribe(channelName: string, callback: SubscriptionCallback) {
-    return this.registerSubscription(channelName, callback).unsubscribe;
-  }
-
-  /**
-   * Subscribes to a channel and resolves once Redis confirms the subscription.
-   */
-  public static async subscribeAsync(channelName: string, callback: SubscriptionCallback) {
-    const subscription = this.registerSubscription(channelName, callback);
-
-    try {
-      await subscription.ready;
-      return subscription.unsubscribe;
-    } catch (error) {
-      subscription.unsubscribe();
-      throw error;
-    }
-  }
-
-  private static registerSubscription(channelName: string, callback: SubscriptionCallback) {
     logger.debug("Adding redis channel callback", { channel: channelName });
 
     // We only want to activate the listener once
@@ -58,18 +38,11 @@ export class ChannelSubscriptionTracker {
 
     const channelSubscriptions = this.subscriptions.get(channelName) ?? new Map<string, SubscriptionCallback>();
     const id = randomUUID();
-    let ready = this.subscriptionReadiness.get(channelName);
 
-    // Subscribe when this channel has no active or pending Redis subscription.
-    if (!ready) {
+    // If there are no subscriptions to the channel, subscribe to it
+    if (channelSubscriptions.size === 0) {
       logger.debug("Subscribing to redis channel", { channel: channelName });
-      ready = this.redis.subscribe(channelName).then(() => undefined);
-      this.subscriptionReadiness.set(channelName, ready);
-      void ready.catch(() => {
-        if (this.subscriptionReadiness.get(channelName) === ready) {
-          this.subscriptionReadiness.delete(channelName);
-        }
-      });
+      void this.redis.subscribe(channelName);
     }
 
     logger.debug("Adding redis channel callback", { channel: channelName, id });
@@ -77,26 +50,24 @@ export class ChannelSubscriptionTracker {
 
     this.subscriptions.set(channelName, channelSubscriptions);
 
-    const unsubscribe = () => {
+    // Return a function to unsubscribe
+    return () => {
       logger.debug("Removing redis channel callback", { channel: channelName, id });
 
-      const currentSubscriptions = this.subscriptions.get(channelName);
-      if (!currentSubscriptions) return;
+      const channelSubscriptions = this.subscriptions.get(channelName);
+      if (!channelSubscriptions) return;
 
-      currentSubscriptions.delete(id);
+      channelSubscriptions.delete(id);
 
       // If there are no subscriptions to the channel, unsubscribe from it
-      if (currentSubscriptions.size >= 1) {
+      if (channelSubscriptions.size >= 1) {
         return;
       }
 
       logger.debug("Unsubscribing from redis channel", { channel: channelName });
       void this.redis.unsubscribe(channelName);
       this.subscriptions.delete(channelName);
-      this.subscriptionReadiness.delete(channelName);
     };
-
-    return { ready, unsubscribe };
   }
 
   /**

packages/request-handler/src/air-quality.spec.ts

@@ -0,0 +1,101 @@
+import { Response } from "undici";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
+
+import { airQualityRequestHandler } from "./air-quality";
+
+vi.mock("@homarr/core/infrastructure/http", () => ({
+  fetchWithTrustedCertificatesAsync: vi.fn(),
+}));
+
+const mockFetch = vi.mocked(fetchWithTrustedCertificatesAsync);
+
+const makeAirQualityResponse = () => {
+  const times = ["2026-07-01T00:00", "2026-07-01T01:00", "2026-07-02T00:00"];
+  const values = [10, 20, 30];
+  const fields = [
+    "european_aqi",
+    "us_aqi",
+    "uv_index",
+    "pm10",
+    "pm2_5",
+    "carbon_monoxide",
+    "nitrogen_dioxide",
+    "sulphur_dioxide",
+    "ozone",
+    "european_aqi_pm2_5",
+    "european_aqi_pm10",
+    "european_aqi_nitrogen_dioxide",
+    "european_aqi_ozone",
+    "european_aqi_sulphur_dioxide",
+    "us_aqi_pm2_5",
+    "us_aqi_pm10",
+    "us_aqi_nitrogen_dioxide",
+    "us_aqi_carbon_monoxide",
+    "us_aqi_ozone",
+    "us_aqi_sulphur_dioxide",
+    "alder_pollen",
+    "birch_pollen",
+    "grass_pollen",
+    "mugwort_pollen",
+    "olive_pollen",
+    "ragweed_pollen",
+  ] as const;
+
+  return {
+    timezone: "Europe/Berlin",
+    utc_offset_seconds: 7200,
+    current: {
+      time: "2026-07-01T12:00",
+      ...Object.fromEntries(fields.map((field) => [field, field === "ragweed_pollen" ? null : 12])),
+    },
+    hourly: {
+      time: times,
+      ...Object.fromEntries(fields.map((field) => [field, field === "ragweed_pollen" ? [null, null, null] : values])),
+    },
+    fields,
+  };
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  airQualityRequestHandler.invalidateCache();
+});
+
+describe("air quality request handler", () => {
+  it("requests and normalizes the full useful forecast field set", async () => {
+    const fixture = makeAirQualityResponse();
+    mockFetch.mockResolvedValue(new Response(JSON.stringify(fixture)));
+
+    const first = await airQualityRequestHandler.handler({ latitude: 48.85, longitude: 2.35 }).getDataAsync();
+    const second = await airQualityRequestHandler.handler({ latitude: 48.85, longitude: 2.35 }).getDataAsync();
+
+    expect(first.data.current.observedAt).toBe("2026-07-01T10:00:00.000Z");
+    expect(first.data.current.pollutants.pm2_5).toBe(12);
+    expect(first.data.current.pollen.ragweed).toBeNull();
+    expect(first.data.hourly[0]?.observedAt).toBe("2026-06-30T22:00:00.000Z");
+    expect(first.data.daily).toEqual([
+      { date: "2026-07-01", europeanAqiMax: 20, usAqiMax: 20, uvIndexMax: 20, pm2_5Max: 20, pm10Max: 20 },
+      { date: "2026-07-02", europeanAqiMax: 30, usAqiMax: 30, uvIndexMax: 30, pm2_5Max: 30, pm10Max: 30 },
+    ]);
+    expect(second.data).toStrictEqual(first.data);
+    expect(mockFetch).toHaveBeenCalledOnce();
+
+    const requestUrl = new URL(String(mockFetch.mock.calls[0]?.[0]));
+    expect(requestUrl.origin).toBe("https://air-quality-api.open-meteo.com");
+    expect(requestUrl.searchParams.get("forecast_days")).toBe("7");
+    expect(requestUrl.searchParams.get("timezone")).toBe("auto");
+    expect(requestUrl.searchParams.get("current")).toContain("european_aqi_pm2_5");
+    expect(requestUrl.searchParams.get("hourly")).toContain("us_aqi_carbon_monoxide");
+    expect(requestUrl.searchParams.get("hourly")).toContain("ragweed_pollen");
+  });
+
+  it("rejects unsuccessful Open-Meteo responses", async () => {
+    mockFetch.mockResolvedValue(new Response("unavailable", { status: 503 }));
+
+    await expect(
+      airQualityRequestHandler.handler({ latitude: 48.85, longitude: 2.35 }).getDataAsync(),
+    ).rejects.toThrow();
+  });
+});

packages/request-handler/src/air-quality.ts

@@ -0,0 +1,283 @@
+import dayjs from "dayjs";
+import timezone from "dayjs/plugin/timezone";
+import utc from "dayjs/plugin/utc";
+import { z } from "zod";
+
+import { ResponseError } from "@homarr/common/server";
+import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
+import { withTimeoutAsync } from "@homarr/core/infrastructure/http/timeout";
+
+import { createWidgetRequestHandler } from "./lib/widget-request-handler";
+
+dayjs.extend(utc);
+dayjs.extend(timezone);
+
+const FORECAST_DAYS = 7;
+
+const requestedVariables = [
+  "european_aqi",
+  "us_aqi",
+  "uv_index",
+  "pm10",
+  "pm2_5",
+  "carbon_monoxide",
+  "nitrogen_dioxide",
+  "sulphur_dioxide",
+  "ozone",
+  "european_aqi_pm2_5",
+  "european_aqi_pm10",
+  "european_aqi_nitrogen_dioxide",
+  "european_aqi_ozone",
+  "european_aqi_sulphur_dioxide",
+  "us_aqi_pm2_5",
+  "us_aqi_pm10",
+  "us_aqi_nitrogen_dioxide",
+  "us_aqi_carbon_monoxide",
+  "us_aqi_ozone",
+  "us_aqi_sulphur_dioxide",
+  "alder_pollen",
+  "birch_pollen",
+  "grass_pollen",
+  "mugwort_pollen",
+  "olive_pollen",
+  "ragweed_pollen",
+] as const;
+
+export const airQualityRequestHandler = createWidgetRequestHandler({
+  cacheTtlMs: 15 * 60 * 1000,
+  fallbackToStaleOnError: true,
+  staleIfErrorTtlMs: 24 * 60 * 60 * 1000,
+  async requestAsync(input: { latitude: number; longitude: number }) {
+    const url = new URL("https://air-quality-api.open-meteo.com/v1/air-quality");
+    url.searchParams.set("latitude", input.latitude.toString());
+    url.searchParams.set("longitude", input.longitude.toString());
+    url.searchParams.set("current", requestedVariables.join(","));
+    url.searchParams.set("hourly", requestedVariables.join(","));
+    url.searchParams.set("forecast_days", FORECAST_DAYS.toString());
+    url.searchParams.set("timezone", "auto");
+
+    const response = await withTimeoutAsync(async (signal) => {
+      return await fetchWithTrustedCertificatesAsync(url.toString(), { signal });
+    });
+    if (!response.ok) throw new ResponseError(response);
+
+    const json: unknown = await response.json();
+    const airQuality = await atLocationOutput.parseAsync(json);
+    const hourly = airQuality.hourly.time.map((value, index) => {
+      return normalizePoint(airQuality.hourly, index, toUtcInstant(value, airQuality.timezone));
+    });
+
+    return {
+      timezone: airQuality.timezone,
+      utcOffsetSeconds: airQuality.utc_offset_seconds,
+      current: normalizePoint(
+        airQuality.current,
+        undefined,
+        toUtcInstant(airQuality.current.time, airQuality.timezone),
+      ),
+      hourly,
+      daily: getDailyMaximums(airQuality.hourly),
+    } satisfies AirQuality;
+  },
+});
+
+const nullableNumber = z.number().nullable();
+const nullableNumberArray = z.array(nullableNumber);
+
+const currentValues = z.object({
+  time: z.string(),
+  european_aqi: nullableNumber,
+  us_aqi: nullableNumber,
+  uv_index: nullableNumber,
+  pm10: nullableNumber,
+  pm2_5: nullableNumber,
+  carbon_monoxide: nullableNumber,
+  nitrogen_dioxide: nullableNumber,
+  sulphur_dioxide: nullableNumber,
+  ozone: nullableNumber,
+  european_aqi_pm2_5: nullableNumber,
+  european_aqi_pm10: nullableNumber,
+  european_aqi_nitrogen_dioxide: nullableNumber,
+  european_aqi_ozone: nullableNumber,
+  european_aqi_sulphur_dioxide: nullableNumber,
+  us_aqi_pm2_5: nullableNumber,
+  us_aqi_pm10: nullableNumber,
+  us_aqi_nitrogen_dioxide: nullableNumber,
+  us_aqi_carbon_monoxide: nullableNumber,
+  us_aqi_ozone: nullableNumber,
+  us_aqi_sulphur_dioxide: nullableNumber,
+  alder_pollen: nullableNumber,
+  birch_pollen: nullableNumber,
+  grass_pollen: nullableNumber,
+  mugwort_pollen: nullableNumber,
+  olive_pollen: nullableNumber,
+  ragweed_pollen: nullableNumber,
+});
+
+const hourlyValues = z.object({
+  time: z.array(z.string()),
+  european_aqi: nullableNumberArray,
+  us_aqi: nullableNumberArray,
+  uv_index: nullableNumberArray,
+  pm10: nullableNumberArray,
+  pm2_5: nullableNumberArray,
+  carbon_monoxide: nullableNumberArray,
+  nitrogen_dioxide: nullableNumberArray,
+  sulphur_dioxide: nullableNumberArray,
+  ozone: nullableNumberArray,
+  european_aqi_pm2_5: nullableNumberArray,
+  european_aqi_pm10: nullableNumberArray,
+  european_aqi_nitrogen_dioxide: nullableNumberArray,
+  european_aqi_ozone: nullableNumberArray,
+  european_aqi_sulphur_dioxide: nullableNumberArray,
+  us_aqi_pm2_5: nullableNumberArray,
+  us_aqi_pm10: nullableNumberArray,
+  us_aqi_nitrogen_dioxide: nullableNumberArray,
+  us_aqi_carbon_monoxide: nullableNumberArray,
+  us_aqi_ozone: nullableNumberArray,
+  us_aqi_sulphur_dioxide: nullableNumberArray,
+  alder_pollen: nullableNumberArray,
+  birch_pollen: nullableNumberArray,
+  grass_pollen: nullableNumberArray,
+  mugwort_pollen: nullableNumberArray,
+  olive_pollen: nullableNumberArray,
+  ragweed_pollen: nullableNumberArray,
+});
+
+const atLocationOutput = z.object({
+  timezone: z.string().min(1),
+  utc_offset_seconds: z.number(),
+  current: currentValues,
+  hourly: hourlyValues,
+});
+
+type CurrentValues = z.infer<typeof currentValues>;
+type HourlyValues = z.infer<typeof hourlyValues>;
+
+const getValue = (values: CurrentValues | HourlyValues, field: keyof Omit<CurrentValues, "time">, index?: number) => {
+  const value = values[field];
+  if (Array.isArray(value)) return value[index ?? 0] ?? null;
+  return value;
+};
+
+const normalizePoint = (
+  values: CurrentValues | HourlyValues,
+  index: number | undefined,
+  observedAt: string,
+): AirQualityPoint => ({
+  observedAt,
+  europeanAqi: getValue(values, "european_aqi", index),
+  usAqi: getValue(values, "us_aqi", index),
+  uvIndex: getValue(values, "uv_index", index),
+  pollutants: {
+    pm2_5: getValue(values, "pm2_5", index),
+    pm10: getValue(values, "pm10", index),
+    ozone: getValue(values, "ozone", index),
+    nitrogenDioxide: getValue(values, "nitrogen_dioxide", index),
+    sulphurDioxide: getValue(values, "sulphur_dioxide", index),
+    carbonMonoxide: getValue(values, "carbon_monoxide", index),
+  },
+  europeanSubIndices: {
+    pm2_5: getValue(values, "european_aqi_pm2_5", index),
+    pm10: getValue(values, "european_aqi_pm10", index),
+    ozone: getValue(values, "european_aqi_ozone", index),
+    nitrogenDioxide: getValue(values, "european_aqi_nitrogen_dioxide", index),
+    sulphurDioxide: getValue(values, "european_aqi_sulphur_dioxide", index),
+    carbonMonoxide: null,
+  },
+  usSubIndices: {
+    pm2_5: getValue(values, "us_aqi_pm2_5", index),
+    pm10: getValue(values, "us_aqi_pm10", index),
+    ozone: getValue(values, "us_aqi_ozone", index),
+    nitrogenDioxide: getValue(values, "us_aqi_nitrogen_dioxide", index),
+    sulphurDioxide: getValue(values, "us_aqi_sulphur_dioxide", index),
+    carbonMonoxide: getValue(values, "us_aqi_carbon_monoxide", index),
+  },
+  pollen: {
+    alder: getValue(values, "alder_pollen", index),
+    birch: getValue(values, "birch_pollen", index),
+    grass: getValue(values, "grass_pollen", index),
+    mugwort: getValue(values, "mugwort_pollen", index),
+    olive: getValue(values, "olive_pollen", index),
+    ragweed: getValue(values, "ragweed_pollen", index),
+  },
+});
+
+const getDailyMaximums = (hourly: HourlyValues): AirQuality["daily"] => {
+  const grouped = new Map<string, AirQuality["daily"][number]>();
+
+  hourly.time.forEach((time, index) => {
+    const date = time.slice(0, 10);
+    const existing = grouped.get(date) ?? {
+      date,
+      europeanAqiMax: null,
+      usAqiMax: null,
+      uvIndexMax: null,
+      pm2_5Max: null,
+      pm10Max: null,
+    };
+
+    existing.europeanAqiMax = maxNullable(existing.europeanAqiMax, hourly.european_aqi[index]);
+    existing.usAqiMax = maxNullable(existing.usAqiMax, hourly.us_aqi[index]);
+    existing.uvIndexMax = maxNullable(existing.uvIndexMax, hourly.uv_index[index]);
+    existing.pm2_5Max = maxNullable(existing.pm2_5Max, hourly.pm2_5[index]);
+    existing.pm10Max = maxNullable(existing.pm10Max, hourly.pm10[index]);
+    grouped.set(date, existing);
+  });
+
+  return Array.from(grouped.values()).slice(0, FORECAST_DAYS);
+};
+
+const maxNullable = (current: number | null, candidate: number | null | undefined): number | null => {
+  if (candidate === null || candidate === undefined) return current;
+  if (current === null) return candidate;
+  return Math.max(current, candidate);
+};
+
+const toUtcInstant = (value: string, timeZone: string): string => {
+  const parsed = dayjs.tz(value, timeZone);
+  if (!parsed.isValid()) throw new Error(`Invalid air quality timestamp: ${value}`);
+  return parsed.utc().toISOString();
+};
+
+export interface AirQualityPollutants {
+  pm2_5: number | null;
+  pm10: number | null;
+  ozone: number | null;
+  nitrogenDioxide: number | null;
+  sulphurDioxide: number | null;
+  carbonMonoxide: number | null;
+}
+
+export interface AirQualityPoint {
+  observedAt: string;
+  europeanAqi: number | null;
+  usAqi: number | null;
+  uvIndex: number | null;
+  pollutants: AirQualityPollutants;
+  europeanSubIndices: AirQualityPollutants;
+  usSubIndices: AirQualityPollutants;
+  pollen: {
+    alder: number | null;
+    birch: number | null;
+    grass: number | null;
+    mugwort: number | null;
+    olive: number | null;
+    ragweed: number | null;
+  };
+}
+
+export interface AirQuality {
+  timezone: string;
+  utcOffsetSeconds: number;
+  current: AirQualityPoint;
+  hourly: AirQualityPoint[];
+  daily: {
+    date: string;
+    europeanAqiMax: number | null;
+    usAqiMax: number | null;
+    uvIndexMax: number | null;
+    pm2_5Max: number | null;
+    pm10Max: number | null;
+  }[];
+}

packages/request-handler/src/lib/widget-request-handler.ts

@@ -2,11 +2,14 @@ import { createRequestHandler } from "./request-handler";
 
 interface Options<TData, TInput extends Record<string, unknown>> {
   requestAsync: (input: TInput) => Promise<TData>;
+  cacheTtlMs?: number;
+  fallbackToStaleOnError?: boolean;
+  staleIfErrorTtlMs?: number;
 }
 
 export const createWidgetRequestHandler = <TData, TInput extends Record<string, unknown>>(
   options: Options<TData, TInput>,
 ) => {
-  const inner = createRequestHandler<TData, TInput>({ requestAsync: options.requestAsync });
+  const inner = createRequestHandler<TData, TInput>(options);
   return inner;
 };

packages/request-handler/src/weather.spec.ts

@@ -0,0 +1,112 @@
+import { Response } from "undici";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
+
+import { weatherRequestHandler } from "./weather";
+
+vi.mock("@homarr/core/infrastructure/http", () => ({
+  fetchWithTrustedCertificatesAsync: vi.fn(),
+}));
+
+const mockFetch = vi.mocked(fetchWithTrustedCertificatesAsync);
+
+const makeWeatherResponse = () => {
+  const hours = Array.from({ length: 25 }, (_, index) => `2026-07-01T${String(index % 24).padStart(2, "0")}:00`);
+  const days = [
+    "2026-06-30",
+    ...Array.from({ length: 7 }, (_, index) => `2026-07-${String(index + 1).padStart(2, "0")}`),
+  ];
+  const hourlyValues = hours.map<number | null>((_, index) => index);
+  const dailyValues = days.map<number | null>((_, index) => index);
+  const sunrise = days.map<string | null>((day) => `${day}T05:00`);
+
+  return {
+    timezone: "Europe/Berlin",
+    utc_offset_seconds: 7200,
+    current: {
+      time: "2026-07-01T12:00",
+      temperature_2m: 24,
+      relative_humidity_2m: 55,
+      apparent_temperature: 25,
+      is_day: 1,
+      precipitation: 0,
+      weather_code: 1,
+      wind_speed_10m: 12,
+      wind_gusts_10m: 20,
+    },
+    hourly: {
+      time: hours,
+      temperature_2m: hourlyValues,
+      apparent_temperature: hourlyValues,
+      precipitation_probability: hourlyValues,
+      precipitation: hourlyValues,
+      weather_code: hourlyValues,
+      relative_humidity_2m: hourlyValues,
+      wind_speed_10m: hourlyValues,
+      wind_gusts_10m: hourlyValues,
+    },
+    daily: {
+      time: days,
+      weather_code: dailyValues,
+      temperature_2m_max: dailyValues,
+      temperature_2m_min: dailyValues,
+      apparent_temperature_max: dailyValues,
+      apparent_temperature_min: dailyValues,
+      precipitation_probability_max: dailyValues,
+      precipitation_sum: dailyValues,
+      relative_humidity_2m_mean: dailyValues,
+      wind_speed_10m_max: dailyValues,
+      wind_gusts_10m_max: dailyValues,
+      uv_index_max: dailyValues,
+      sunrise,
+      sunset: days.map((day) => `${day}T21:00`),
+      daylight_duration: dailyValues,
+    },
+  };
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  weatherRequestHandler.invalidateCache();
+});
+
+describe("weather request handler", () => {
+  it("requests bounded useful forecasts and normalizes location times", async () => {
+    const response = makeWeatherResponse();
+    response.hourly.temperature_2m = [null];
+    Reflect.deleteProperty(response.hourly, "wind_gusts_10m");
+    response.daily.sunrise[1] = null;
+    mockFetch.mockResolvedValue(new Response(JSON.stringify(response)));
+
+    const first = await weatherRequestHandler.handler({ latitude: 48.85, longitude: 2.35 }).getDataAsync();
+    const second = await weatherRequestHandler.handler({ latitude: 48.85, longitude: 2.35 }).getDataAsync();
+
+    expect(first.data.current.observedAt).toBe("2026-07-01T10:00:00.000Z");
+    expect(first.data.hourly).toHaveLength(24);
+    expect(first.data.daily).toHaveLength(7);
+    expect(first.data.daily[0]?.date).toBe("2026-07-01");
+    expect(first.data.hourly[0]?.temperature).toBeNull();
+    expect(first.data.hourly[1]?.temperature).toBeNull();
+    expect(first.data.hourly[0]?.windGusts).toBeNull();
+    expect(first.data.daily[0]?.sunriseAt).toBeNull();
+    expect(first.data.daily[1]?.sunriseAt).toBe("2026-07-02T03:00:00.000Z");
+    expect(second.data).toStrictEqual(first.data);
+    expect(mockFetch).toHaveBeenCalledOnce();
+
+    const requestUrl = new URL(String(mockFetch.mock.calls[0]?.[0]));
+    expect(requestUrl.searchParams.get("forecast_hours")).toBe("24");
+    expect(requestUrl.searchParams.get("forecast_days")).toBe("7");
+    expect(requestUrl.searchParams.has("past_days")).toBe(false);
+    expect(requestUrl.searchParams.get("timezone")).toBe("auto");
+    expect(requestUrl.searchParams.get("current")).toContain("apparent_temperature");
+    expect(requestUrl.searchParams.get("hourly")).toContain("precipitation_probability");
+    expect(requestUrl.searchParams.get("daily")).toContain("uv_index_max");
+  });
+
+  it("rejects unsuccessful Open-Meteo responses", async () => {
+    mockFetch.mockResolvedValue(new Response("unavailable", { status: 503 }));
+
+    await expect(weatherRequestHandler.handler({ latitude: 48.85, longitude: 2.35 }).getDataAsync()).rejects.toThrow();
+  });
+});

packages/request-handler/src/weather.ts

@@ -1,73 +1,255 @@
+import dayjs from "dayjs";
+import timezone from "dayjs/plugin/timezone";
+import utc from "dayjs/plugin/utc";
 import { z } from "zod";
 
+import { ResponseError } from "@homarr/common/server";
 import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
 import { withTimeoutAsync } from "@homarr/core/infrastructure/http/timeout";
 
 import { createWidgetRequestHandler } from "./lib/widget-request-handler";
 
+dayjs.extend(utc);
+dayjs.extend(timezone);
+
+const HOURLY_FORECAST_LENGTH = 24;
+const DAILY_FORECAST_LENGTH = 7;
+
+const requestWeatherAsync = async (input: { latitude: number; longitude: number }): Promise<Weather> => {
+  const url = new URL("https://api.open-meteo.com/v1/forecast");
+  url.searchParams.set("latitude", input.latitude.toString());
+  url.searchParams.set("longitude", input.longitude.toString());
+  url.searchParams.set(
+    "current",
+    [
+      "temperature_2m",
+      "relative_humidity_2m",
+      "apparent_temperature",
+      "is_day",
+      "precipitation",
+      "weather_code",
+      "wind_speed_10m",
+      "wind_gusts_10m",
+    ].join(","),
+  );
+  url.searchParams.set(
+    "hourly",
+    [
+      "temperature_2m",
+      "apparent_temperature",
+      "precipitation_probability",
+      "precipitation",
+      "weather_code",
+      "relative_humidity_2m",
+      "wind_speed_10m",
+      "wind_gusts_10m",
+    ].join(","),
+  );
+  url.searchParams.set(
+    "daily",
+    [
+      "weather_code",
+      "temperature_2m_max",
+      "temperature_2m_min",
+      "apparent_temperature_max",
+      "apparent_temperature_min",
+      "precipitation_probability_max",
+      "precipitation_sum",
+      "relative_humidity_2m_mean",
+      "wind_speed_10m_max",
+      "wind_gusts_10m_max",
+      "uv_index_max",
+      "sunrise",
+      "sunset",
+      "daylight_duration",
+    ].join(","),
+  );
+  url.searchParams.set("timezone", "auto");
+  url.searchParams.set("forecast_hours", HOURLY_FORECAST_LENGTH.toString());
+  url.searchParams.set("forecast_days", DAILY_FORECAST_LENGTH.toString());
+
+  const res = await withTimeoutAsync(async (signal) => {
+    return await fetchWithTrustedCertificatesAsync(url.toString(), { signal });
+  });
+  if (!res.ok) throw new ResponseError(res);
+
+  const json: unknown = await res.json();
+  const weather = await atLocationOutput.parseAsync(json);
+  const currentLocalDate = weather.current.time.slice(0, 10);
+  const matchedCurrentDayIndex = weather.daily.time.indexOf(currentLocalDate);
+  const currentDayIndex = matchedCurrentDayIndex < 0 ? 0 : matchedCurrentDayIndex;
+  const dailyIndexes = weather.daily.time
+    .map((_, index) => index)
+    .slice(currentDayIndex, currentDayIndex + DAILY_FORECAST_LENGTH);
+  return {
+    timezone: weather.timezone,
+    utcOffsetSeconds: weather.utc_offset_seconds,
+    current: {
+      observedAt: toUtcInstant(weather.current.time, weather.timezone),
+      temperature: weather.current.temperature_2m,
+      apparentTemperature: weather.current.apparent_temperature,
+      relativeHumidity: weather.current.relative_humidity_2m,
+      precipitation: weather.current.precipitation,
+      weatherCode: weather.current.weather_code,
+      weathercode: weather.current.weather_code,
+      windSpeed: weather.current.wind_speed_10m,
+      windspeed: weather.current.wind_speed_10m,
+      windGusts: weather.current.wind_gusts_10m,
+      isDay: weather.current.is_day === 1,
+    },
+    hourly: weather.hourly.time.slice(0, HOURLY_FORECAST_LENGTH).map((value, index) => {
+      return {
+        observedAt: toUtcInstant(value, weather.timezone),
+        temperature: weather.hourly.temperature_2m[index] ?? null,
+        apparentTemperature: weather.hourly.apparent_temperature[index] ?? null,
+        precipitationProbability: weather.hourly.precipitation_probability[index] ?? null,
+        precipitation: weather.hourly.precipitation[index] ?? null,
+        weatherCode: weather.hourly.weather_code[index] ?? null,
+        relativeHumidity: weather.hourly.relative_humidity_2m[index] ?? null,
+        windSpeed: weather.hourly.wind_speed_10m[index] ?? null,
+        windGusts: weather.hourly.wind_gusts_10m[index] ?? null,
+      };
+    }),
+    daily: dailyIndexes.map((index) => {
+      const value = weather.daily.time[index] ?? currentLocalDate;
+      return {
+        date: value,
+        time: value,
+        weatherCode: weather.daily.weather_code[index] ?? 404,
+        maxTemperature: weather.daily.temperature_2m_max[index] ?? null,
+        maxTemp: weather.daily.temperature_2m_max[index] ?? undefined,
+        minTemperature: weather.daily.temperature_2m_min[index] ?? null,
+        minTemp: weather.daily.temperature_2m_min[index] ?? undefined,
+        maxApparentTemperature: weather.daily.apparent_temperature_max[index] ?? null,
+        minApparentTemperature: weather.daily.apparent_temperature_min[index] ?? null,
+        precipitationProbability: weather.daily.precipitation_probability_max[index] ?? null,
+        precipitation: weather.daily.precipitation_sum[index] ?? null,
+        averageHumidity: weather.daily.relative_humidity_2m_mean[index] ?? null,
+        humidity: weather.daily.relative_humidity_2m_mean[index] ?? undefined,
+        maxWindSpeed: weather.daily.wind_speed_10m_max[index] ?? null,
+        maxWindGusts: weather.daily.wind_gusts_10m_max[index] ?? null,
+        uvIndex: weather.daily.uv_index_max[index] ?? null,
+        sunriseAt: toOptionalUtcInstant(weather.daily.sunrise[index], weather.timezone),
+        sunrise: weather.daily.sunrise[index] ?? undefined,
+        sunsetAt: toOptionalUtcInstant(weather.daily.sunset[index], weather.timezone),
+        sunset: weather.daily.sunset[index] ?? undefined,
+        daylightDuration: weather.daily.daylight_duration[index] ?? null,
+      };
+    }),
+  } satisfies Weather;
+};
+
 export const weatherRequestHandler = createWidgetRequestHandler({
-  async requestAsync(input: { latitude: number; longitude: number }) {
-    const res = await withTimeoutAsync(async (signal) => {
-      return await fetchWithTrustedCertificatesAsync(
-        `https://api.open-meteo.com/v1/forecast?latitude=${input.latitude}&longitude=${input.longitude}&daily=weathercode,temperature_2m_max,temperature_2m_min,sunrise,sunset,wind_speed_10m_max,wind_gusts_10m_max,relative_humidity_2m_mean&current_weather=true&timezone=auto`,
-        { signal },
-      );
-    });
-    const json: unknown = await res.json();
-    const weather = await atLocationOutput.parseAsync(json);
-    return {
-      current: weather.current_weather,
-      daily: weather.daily.time.map((value, index) => {
-        return {
-          time: value,
-          weatherCode: weather.daily.weathercode[index] ?? 404,
-          maxTemp: weather.daily.temperature_2m_max[index],
-          minTemp: weather.daily.temperature_2m_min[index],
-          sunrise: weather.daily.sunrise[index],
-          sunset: weather.daily.sunset[index],
-          maxWindSpeed: weather.daily.wind_speed_10m_max[index],
-          maxWindGusts: weather.daily.wind_gusts_10m_max[index],
-          humidity: weather.daily.relative_humidity_2m_mean[index],
-        };
-      }),
-    } satisfies Weather;
-  },
+  cacheTtlMs: 5 * 60 * 1000,
+  requestAsync: requestWeatherAsync,
 });
 
+const nullableNumberArray = z.array(z.number().nullable()).default([]);
+const nullableStringArray = z.array(z.string().nullable()).default([]);
+
 const atLocationOutput = z.object({
-  current_weather: z.object({
-    weathercode: z.number(),
-    temperature: z.number(),
-    windspeed: z.number(),
+  timezone: z.string().min(1),
+  utc_offset_seconds: z.number(),
+  current: z.object({
+    time: z.string(),
+    temperature_2m: z.number(),
+    relative_humidity_2m: z.number(),
+    apparent_temperature: z.number(),
+    is_day: z.number(),
+    precipitation: z.number(),
+    weather_code: z.number(),
+    wind_speed_10m: z.number(),
+    wind_gusts_10m: z.number(),
+  }),
+  hourly: z.object({
+    time: z.array(z.string()),
+    temperature_2m: nullableNumberArray,
+    apparent_temperature: nullableNumberArray,
+    precipitation_probability: nullableNumberArray,
+    precipitation: nullableNumberArray,
+    weather_code: nullableNumberArray,
+    relative_humidity_2m: nullableNumberArray,
+    wind_speed_10m: nullableNumberArray,
+    wind_gusts_10m: nullableNumberArray,
   }),
   daily: z.object({
     time: z.array(z.string()),
-    weathercode: z.array(z.number()),
-    temperature_2m_max: z.array(z.number()),
-    temperature_2m_min: z.array(z.number()),
-    sunrise: z.array(z.string()),
-    sunset: z.array(z.string()),
-    wind_speed_10m_max: z.array(z.number()),
-    wind_gusts_10m_max: z.array(z.number()),
-    relative_humidity_2m_mean: z.array(z.number()),
+    weather_code: nullableNumberArray,
+    temperature_2m_max: nullableNumberArray,
+    temperature_2m_min: nullableNumberArray,
+    apparent_temperature_max: nullableNumberArray,
+    apparent_temperature_min: nullableNumberArray,
+    precipitation_probability_max: nullableNumberArray,
+    precipitation_sum: nullableNumberArray,
+    relative_humidity_2m_mean: nullableNumberArray,
+    wind_speed_10m_max: nullableNumberArray,
+    wind_gusts_10m_max: nullableNumberArray,
+    uv_index_max: nullableNumberArray,
+    sunrise: nullableStringArray,
+    sunset: nullableStringArray,
+    daylight_duration: nullableNumberArray,
   }),
 });
 
+const toUtcInstant = (value: string, timeZone: string): string => {
+  const parsed = dayjs.tz(value, timeZone);
+  if (!parsed.isValid()) throw new Error(`Invalid weather timestamp: ${value}`);
+  return parsed.utc().toISOString();
+};
+
+const toOptionalUtcInstant = (value: string | null | undefined, timeZone: string): string | null => {
+  if (!value) return null;
+  return toUtcInstant(value, timeZone);
+};
+
 export interface Weather {
+  timezone: string;
+  utcOffsetSeconds: number;
   current: {
-    weathercode: number;
     temperature: number;
+    apparentTemperature: number;
+    relativeHumidity: number;
+    precipitation: number;
+    weatherCode: number;
+    weathercode: number;
+    windSpeed: number;
     windspeed: number;
+    windGusts: number;
+    isDay: boolean;
+    observedAt: string;
   };
+  hourly: {
+    observedAt: string;
+    temperature: number | null;
+    apparentTemperature: number | null;
+    precipitationProbability: number | null;
+    precipitation: number | null;
+    weatherCode: number | null;
+    relativeHumidity: number | null;
+    windSpeed: number | null;
+    windGusts: number | null;
+  }[];
   daily: {
+    date: string;
     time: string;
     weatherCode: number;
+    maxTemperature: number | null;
     maxTemp: number | undefined;
+    minTemperature: number | null;
     minTemp: number | undefined;
-    sunrise: string | undefined;
-    sunset: string | undefined;
-    maxWindSpeed: number | undefined;
-    maxWindGusts: number | undefined;
+    maxApparentTemperature: number | null;
+    minApparentTemperature: number | null;
+    precipitationProbability: number | null;
+    precipitation: number | null;
+    averageHumidity: number | null;
     humidity: number | undefined;
+    maxWindSpeed: number | null;
+    maxWindGusts: number | null;
+    uvIndex: number | null;
+    sunriseAt: string | null;
+    sunrise: string | undefined;
+    sunsetAt: string | null;
+    sunset: string | undefined;
+    daylightDuration: number | null;
   }[];
 }

packages/translation/src/lang/en.json

@@ -2309,6 +2309,7 @@
       "open": "Open Homarr Assistant",
       "close": "Close assistant",
       "minimize": "Minimize assistant",
+      "windowControls": "Conversation window controls",
       "spotlight": "Ask Homarr Assistant",
       "spotlightDescription": "Type and send a prompt without leaving the command menu.",
       "spotlightPrompt": {
@@ -2326,24 +2327,6 @@
       "newConversation": "New conversation",
       "conversations": "Conversations",
       "delete": "Delete",
-      "cancel": "Cancel",
-      "conversationActions": "Conversation actions",
-      "searchConversations": "Search conversations",
-      "noMatchingConversations": "No matching conversations",
-      "moreActions": "More response actions",
-      "renameConversation": {
-        "action": "Rename",
-        "label": "Conversation name",
-        "save": "Save name",
-        "failedTitle": "Conversation could not be renamed",
-        "failedDescription": "Homarr could not rename this conversation. Try again."
-      },
-      "deleteConversation": {
-        "title": "Delete conversation?",
-        "description": "“{title}” and its messages will be permanently deleted.",
-        "failedTitle": "Conversation could not be deleted",
-        "failedDescription": "Homarr could not delete this conversation. Try again."
-      },
       "closeHistory": "Close conversation history",
       "openHistory": "Open conversation history",
       "emptyTitle": "What can I help with?",
@@ -2416,8 +2399,6 @@
       "regenerate": "Regenerate response",
       "helpful": "Helpful",
       "notHelpful": "Not helpful",
-      "readAloud": "Read response aloud",
-      "stopReading": "Stop reading response",
       "feedbackError": "Your feedback could not be saved. Try again.",
       "exportMarkdown": "Export as Markdown",
       "exportConversation": {
@@ -2446,6 +2427,7 @@
       },
       "mentions": {
         "menu": "Add Homarr context",
+        "hint": "Type @ to add context",
         "context": "Context",
         "app": "Apps",
         "integration": "Integrations",
@@ -2460,6 +2442,7 @@
       },
       "commands": {
         "menu": "Assistant commands",
+        "hint": "Type / for shortcuts",
         "health": "Prepare a service-health check",
         "explore": "Prepare an overview of this Homarr instance",
         "media": "Prepare a media search",
@@ -2572,6 +2555,7 @@
         "otherPlaceholder": "Type another answer…",
         "submit": "Send answer",
         "cancelOther": "Cancel other answer",
+        "automaticAffirmative": "Choosing the affirmative answer automatically",
         "optionKind": {
           "affirmative": "Confirm",
           "negative": "Decline",
@@ -2646,7 +2630,7 @@
       "autoApproval": {
         "label": "Automatic approvals",
         "title": "Automatic approvals",
-        "description": "Automatically prepare forms and approve protected changes for this conversation. Questions still wait for your answer, and your Homarr permissions still apply. This turns off when you switch conversations.",
+        "description": "Automatically approve protected changes, use presented form details, and choose answers categorized as affirmative. Neutral selections still wait for you. Your Homarr permissions still apply. This turns off when you switch conversations.",
         "enable": "Enable for this conversation",
         "disable": "Turn off automatic approvals",
         "enabled": "Automatic approvals are on",
@@ -3169,9 +3153,6 @@
           "label": "24-hour format",
           "description": "Use 24-hour format instead of 12-hour format"
         },
-        "showSeconds": {
-          "label": "Display seconds"
-        },
         "useCustomTimezone": {
           "label": "Use a fixed timezone"
         },
@@ -3183,16 +3164,12 @@
           "label": "Show the date"
         },
         "dateFormat": {
-          "label": "Date Format",
-          "description": "How the date should look like"
+          "label": "Date format",
+          "description": "Choose a Day.js preset. Each option shows a live example and its format tokens."
         },
         "customTimeFormat": {
-          "label": "Custom time format",
-          "description": "Use ISO 8601 to format time (this will override other options)"
-        },
-        "customDateFormat": {
-          "label": "Custom date format",
-          "description": "Use ISO 8601 to format date (this will override other options)"
+          "label": "Time format",
+          "description": "Choose a Day.js preset. The selected format controls 12/24-hour display and whether the clock updates every second."
         },
         "showWeather": {
           "label": "Show weather",
@@ -3203,7 +3180,317 @@
         },
         "isWeatherFormatFahrenheit": {
           "label": "Use Fahrenheit"
+        },
+        "animateWeatherIcon": {
+          "label": "Animate weather icon",
+          "description": "Animate the weather icon. Disabled by default and always disabled when reduced motion is requested."
+        },
+        "worldClockCities": {
+          "label": "World clock cities",
+          "description": "Add and order up to six cities for advanced view."
         }
+      },
+      "timezoneList": {
+        "timezone": "Timezone",
+        "cityLabel": "City label",
+        "searchPlaceholder": "Search timezones",
+        "noResults": "No timezones found",
+        "unsupportedOption": "Unsupported: {timeZone}",
+        "add": "Add city",
+        "remove": "Remove {city}",
+        "reorder": "Reorder {city}",
+        "limit": "{count} of {maximum} cities configured"
+      },
+      "worldClock": {
+        "primary": "Primary clock",
+        "local": "Local time",
+        "today": "Today",
+        "tomorrow": "Tomorrow",
+        "yesterday": "Yesterday",
+        "noSecondaryCities": "Add cities in widget options to compare them here.",
+        "unsupportedPrimaryTitle": "Primary timezone is unavailable",
+        "unsupportedPrimary": "{timeZone} is not supported in this browser. Showing UTC as a clearly marked fallback.",
+        "unsupportedTimeZone": "Unsupported timezone: {timeZone}",
+        "accessibleTime": "{city}: {time}, {date}, {timeZone}",
+        "advancedLabel": "Advanced world clock",
+        "cities": "World clocks",
+        "cityCount": "{count} timezones",
+        "timeBarLabel": "24-hour time-of-day position for {city}",
+        "dayProgress": "{percent}% elapsed · {hours}h {minutes}m remaining",
+        "phaseLegend": "Time-of-day legend",
+        "tick": {
+          "midnight": "00",
+          "morning": "06",
+          "noon": "12",
+          "evening": "18",
+          "end": "24"
+        },
+        "phaseRange": {
+          "night": "00–05 · 21–24",
+          "dawn": "05–08",
+          "day": "08–18",
+          "dusk": "18–21"
+        },
+        "phase": {
+          "night": "Night",
+          "dawn": "Dawn",
+          "day": "Day",
+          "dusk": "Dusk"
+        }
+      }
+    },
+    "airQuality": {
+      "name": "Air Quality & UV",
+      "description": "Displays air quality, ultraviolet index, pollutants and pollen for a location.",
+      "option": {
+        "location": {
+          "label": "Air quality location"
+        },
+        "aqiStandard": {
+          "label": "AQI standard",
+          "options": {
+            "auto": "Automatic for locale",
+            "european": "European AQI",
+            "us": "US AQI"
+          }
+        },
+        "showUv": {
+          "label": "Show UV index"
+        },
+        "showPollutants": {
+          "label": "Show pollutant concentrations"
+        },
+        "showPollen": {
+          "label": "Show pollen concentrations"
+        }
+      },
+      "category": {
+        "good": "Good",
+        "fair": "Fair",
+        "moderate": "Moderate",
+        "unhealthySensitive": "Unhealthy for sensitive groups",
+        "unhealthy": "Unhealthy",
+        "poor": "Poor",
+        "veryPoor": "Very poor",
+        "veryUnhealthy": "Very unhealthy",
+        "extremelyPoor": "Extremely poor",
+        "hazardous": "Hazardous",
+        "unknown": "No AQI reading"
+      },
+      "uv": {
+        "label": "UV index",
+        "category": {
+          "low": "Low",
+          "moderate": "Moderate",
+          "high": "High",
+          "veryHigh": "Very high",
+          "extreme": "Extreme",
+          "unknown": "No reading"
+        }
+      },
+      "dominantPollutant": "Dominant pollutant",
+      "aqiLabel": "AQI",
+      "strongestPollen": "Highest pollen",
+      "unit": {
+        "concentration": "{value} µg/m³",
+        "pollen": "{value} grains/m³"
+      },
+      "pollutant": {
+        "pm2_5": "PM2.5",
+        "pm10": "PM10",
+        "ozone": "Ozone",
+        "nitrogenDioxide": "Nitrogen dioxide",
+        "sulphurDioxide": "Sulphur dioxide",
+        "carbonMonoxide": "Carbon monoxide"
+      },
+      "pollen": {
+        "alder": "Alder",
+        "birch": "Birch",
+        "grass": "Grass",
+        "mugwort": "Mugwort",
+        "olive": "Olive",
+        "ragweed": "Ragweed"
+      },
+      "compact": {
+        "sixHourTrend": "AQI trend for the next six hours"
+      },
+      "advanced": {
+        "observedAt": "Updated at {time}",
+        "next24Hours": "Next 24 hours",
+        "pollutants": "Pollutant concentrations",
+        "pollen": "Pollen concentrations",
+        "sevenDayForecast": "7-day maximum forecast",
+        "aqiValue": "AQI {value}",
+        "uvValue": "UV {value}",
+        "uvShort": "UV {value}",
+        "noForecast": "No forecast data available"
+      }
+    },
+    "countdown": {
+      "name": "Countdowns",
+      "description": "Tracks upcoming events and recurring anniversaries.",
+      "option": {
+        "events": {
+          "label": "Events",
+          "description": "Add and order up to 20 one-time or yearly countdowns. Dates are entered in the selected timezone."
+        },
+        "showProgress": {
+          "label": "Show progress"
+        },
+        "showSeconds": {
+          "label": "Show seconds",
+          "description": "Keep seconds visible for every upcoming event."
+        }
+      },
+      "dateTimeEventList": {
+        "newEvent": "New event",
+        "add": "Add event",
+        "remove": "Remove {event}",
+        "reorder": "Reorder {event}",
+        "eventLabel": "Event label",
+        "timezone": "Timezone",
+        "unsupportedOption": "Unsupported: {timeZone}",
+        "recurrence": "Repeats",
+        "recurrenceOption": {
+          "none": "Does not repeat",
+          "yearly": "Every year"
+        },
+        "target": "Event date and time",
+        "trackProgress": "Track progress from a start date",
+        "start": "Progress start date and time",
+        "confirmDateTime": "Confirm date and time",
+        "limit": "{count} of {maximum} events configured"
+      },
+      "empty": {
+        "title": "No countdowns yet",
+        "description": "Add an event in widget options to start counting down."
+      },
+      "completed": "Completed",
+      "yearly": "Yearly",
+      "progress": "Event progress",
+      "upcoming": "Upcoming",
+      "completedEvents": "Completed events",
+      "invalid": {
+        "title": "Some events cannot be displayed",
+        "description": "{count, plural, one {One event has an invalid date or unsupported timezone.} other {# events have an invalid date or unsupported timezone.}}",
+        "value": "Unavailable"
+      },
+      "alert": {
+        "notifications": "Browser notifications",
+        "permissionDenied": "Notifications are blocked in this browser.",
+        "reached": "The countdown has reached its target."
+      }
+    },
+    "timer": {
+      "name": "Timer / Pomodoro",
+      "description": "Runs a simple timer or a configurable Pomodoro sequence.",
+      "option": {
+        "mode": {
+          "label": "Mode",
+          "options": {
+            "timer": "Timer",
+            "pomodoro": "Pomodoro"
+          }
+        },
+        "timerMinutes": {
+          "label": "Timer minutes"
+        },
+        "focusMinutes": {
+          "label": "Focus minutes"
+        },
+        "shortBreakMinutes": {
+          "label": "Short break minutes"
+        },
+        "longBreakMinutes": {
+          "label": "Long break minutes"
+        },
+        "sessionsBeforeLongBreak": {
+          "label": "Focus sessions before a long break"
+        },
+        "autoStartBreaks": {
+          "label": "Automatically start breaks"
+        },
+        "autoStartFocus": {
+          "label": "Automatically start focus sessions"
+        }
+      },
+      "phase": {
+        "timer": "Timer",
+        "focus": "Focus",
+        "shortBreak": "Short break",
+        "longBreak": "Long break"
+      },
+      "action": {
+        "start": "Start",
+        "pause": "Pause",
+        "reset": "Reset"
+      },
+      "attention": {
+        "timerComplete": "Timer complete",
+        "phaseReady": "{phase} ready"
+      },
+      "progress": "Timer progress: {progress}%",
+      "compact": {
+        "completedFocus": "{count, plural, =0 {No focus sessions completed} one {# focus session completed} other {# focus sessions completed}}"
+      },
+      "alert": {
+        "title": "Timer complete",
+        "completed": "{phase} completed."
+      },
+      "advanced": {
+        "sequence": "Pomodoro sequence",
+        "focusSession": "Focus {session}",
+        "settings": "Permanent settings",
+        "settingsHint": "Use the widget context menu to edit these board settings.",
+        "localAlerts": "Local alerts",
+        "notifications": "Browser notifications",
+        "sound": "Timer sounds",
+        "localAlertsHint": "Timer sounds are enabled by default. Sounds and notifications apply only to this widget in this browser.",
+        "notificationsDenied": "Notifications are blocked in this browser."
+      }
+    },
+    "today": {
+      "name": "Today",
+      "description": "Displays the current date and progress through the calendar.",
+      "option": {
+        "weekConvention": {
+          "label": "Week numbering",
+          "options": {
+            "locale": "Use locale rules",
+            "iso": "ISO 8601"
+          }
+        },
+        "showWeekNumber": {
+          "label": "Show week number"
+        },
+        "showDayOfYear": {
+          "label": "Show day of year"
+        },
+        "showQuarter": {
+          "label": "Show quarter"
+        },
+        "showYearProgress": {
+          "label": "Show year progress"
+        }
+      },
+      "weekNumber": "Week {week}",
+      "dayOfYear": "Day {day} of {total}",
+      "quarter": "Quarter {quarter}",
+      "daysAfterToday": "{days, plural, =0 {Last day of the year} one {# day after today} other {# days after today}}",
+      "weekProgressLabel": "Week progress",
+      "monthProgressLabel": "Month progress",
+      "yearProgressLabel": "Year progress",
+      "yearProgress": "Year progress: {progress}%",
+      "weekConvention": {
+        "locale": "Week numbers follow your locale",
+        "iso": "ISO 8601 week numbers"
+      },
+      "advanced": {
+        "week": "Week number",
+        "dayOfYear": "Day of year",
+        "quarter": "Quarter",
+        "quarterValue": "Q{quarter}",
+        "daysRemaining": "Days after today"
       }
     },
     "minecraftServerStatus": {
@@ -3599,6 +3886,13 @@
         "disableTemperatureDecimals": {
           "label": "Disable temperature decimals"
         },
+        "animateIcons": {
+          "label": "Animate weather icons"
+        },
+        "showHumidity": {
+          "label": "Show humidity",
+          "description": "Display humidity in current conditions, hourly details and daily forecasts"
+        },
         "showCurrentWindSpeed": {
           "label": "Show current wind speed",
           "description": "Only on current weather"
@@ -3652,11 +3946,40 @@
       "detailsFor": "Show weather details for {date}",
       "advanced": {
         "forecast": "7-day forecast",
+        "hourlyForecast": "Next 24 hours",
         "day": "Day",
+        "time": "Time",
         "conditions": "Conditions",
-        "temperature": "High / low",
+        "temperature": "Temperature",
+        "feelsLike": "Feels like {temperature}",
+        "feelsLikeLabel": "Feels like",
+        "feelsLikeRange": "Feels like: {maximum} / {minimum}",
+        "highLow": "High {maximum} · low {minimum}",
+        "observedAt": "Updated at {time}",
         "humidity": "Humidity",
+        "averageHumidity": "Average humidity: {humidity}%",
+        "currentHumidity": "Current humidity",
         "wind": "Wind / gusts ({unit})",
+        "currentWind": "Current wind / gusts",
+        "windValue": "{speed} / {gusts} {unit}",
+        "windDetail": "Max wind / gusts: {speed} / {gusts} {unit}",
+        "nextHourPrecipitation": "Precipitation next hour",
+        "precipitationChance": "Precipitation chance",
+        "precipitationValue": "{probability}% · {amount} mm",
+        "precipitationDetail": "Precipitation: {probability}% · {amount} mm",
+        "todayUv": "Today's max UV index",
+        "uvIndex": "Max UV index: {value}",
+        "daylight": "Daylight: {duration}",
+        "hourlyTooltip": "Feels like {feelsLike}{temperatureUnit} · {amount} mm · {humidity}% humidity · {speed} {speedUnit} wind",
+        "hourlyTooltipWithoutHumidity": "Feels like {feelsLike}{temperatureUnit} · {amount} mm · {speed} {speedUnit} wind",
+        "detailLabel": {
+          "feelsLike": "Feels like",
+          "precipitation": "Precipitation",
+          "humidity": "Average humidity",
+          "wind": "Max wind / gusts",
+          "uv": "Max UV index",
+          "daylight": "Daylight"
+        },
         "sun": "Sunrise / sunset",
         "noForecast": "No forecast data available"
       }
@@ -5760,13 +6083,7 @@
       "compact": {
         "title": "Assistant",
         "description": "Resize this widget to chat here, or open the full conversation.",
-        "open": "Open assistant",
-        "openTitle": "Assistant open in side panel",
-        "openDescription": "The conversation stays in one active surface.",
-        "returnToWidget": "Return the conversation to this widget",
-        "otherWidgetTitle": "Assistant active in another widget",
-        "otherWidgetDescription": "Only one conversation surface stays active at a time.",
-        "useHere": "Use the assistant in this widget"
+        "open": "Open assistant"
       }
     }
   },
@@ -8407,10 +8724,6 @@
     }
   },
   "log": {
-    "context": {
-      "widgetError": "Widget reported an error around this time",
-      "expiredWidgetError": "Logs around this widget error are no longer retained"
-    },
     "level": {
       "option": {
         "debug": "Debug",

packages/widgets/package.json

@@ -65,6 +65,7 @@
     "@mantine/dates": "catalog:",
     "@mantine/form": "catalog:",
     "@mantine/hooks": "catalog:",
+    "@rexa-developer/tiks": "catalog:",
     "@tabler/icons-react": "catalog:",
     "@tiptap/extension-color": "catalog:",
     "@tiptap/extension-highlight": "catalog:",

packages/widgets/src/_inputs/index.ts

@@ -3,6 +3,7 @@ import { WidgetAnchorNoteInput } from "./widget-anchor-note-input";
 import { WidgetAppInput } from "./widget-app-input";
 import { WidgetCustomWidgetSelectInput } from "./widget-custom-widget-select-input";
 import { WidgetCustomWidgetConfigurationInput } from "./widget-custom-widget-configuration-input";
+import { WidgetDateTimeEventListInput } from "./widget-date-time-event-list-input";
 import { WidgetDynamicSelectInput } from "./widget-dynamic-select-input";
 import { WidgetDynamicMultiSelectInput } from "./widget-dynamic-multiselect-input";
 import { WidgetLocationInput } from "./widget-location-input";
@@ -15,6 +16,7 @@ import { WidgetSliderInput } from "./widget-slider-input";
 import { WidgetSortedItemListInput } from "./widget-sortable-item-list-input";
 import { WidgetSwitchInput } from "./widget-switch-input";
 import { WidgetTextInput } from "./widget-text-input";
+import { WidgetTimezoneListInput } from "./widget-timezone-list-input";
 import { WidgetUmamiEventInput } from "./widget-umami-event-input";
 import { WidgetUmamiEventNamesInput } from "./widget-umami-event-names-input";
 import { WidgetUmamiWebsiteInput } from "./widget-umami-website-input";
@@ -26,6 +28,8 @@ const mapping = {
   internal: WidgetInternalInput,
   anchorNote: WidgetAnchorNoteInput,
   text: WidgetTextInput,
+  dateTimeEventList: WidgetDateTimeEventListInput,
+  timezoneList: WidgetTimezoneListInput,
   location: WidgetLocationInput,
   multiSelect: WidgetMultiSelectInput,
   multiText: WidgetMultiTextInput,

packages/widgets/src/_inputs/widget-date-time-event-list-input.tsx

@@ -0,0 +1,317 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import {
+  closestCenter,
+  DndContext,
+  KeyboardSensor,
+  MouseSensor,
+  TouchSensor,
+  useSensor,
+  useSensors,
+} from "@dnd-kit/core";
+import {
+  arrayMove,
+  SortableContext,
+  sortableKeyboardCoordinates,
+  useSortable,
+  verticalListSortingStrategy,
+} from "@dnd-kit/sortable";
+import { ActionIcon, Button, Card, Fieldset, Group, Select, Stack, Switch, Text, TextInput } from "@mantine/core";
+import { DateTimePicker } from "@mantine/dates";
+import { IconGripVertical, IconPlus, IconTrash } from "@tabler/icons-react";
+import dayjs from "dayjs";
+
+import { createId } from "@homarr/common";
+import type { WidgetKind } from "@homarr/definitions";
+import { useScopedI18n } from "@homarr/translation/client";
+
+import { formatWallDateTime, resolveWallDateTimeString } from "../countdown/recurrence";
+import type { DateTimeEventRecurrence, OptionDateTimeEvent } from "../options";
+import type { CommonWidgetInputProps } from "./common";
+import { useWidgetInputTranslation } from "./common";
+import { useFormContext } from "./form";
+
+export const WidgetDateTimeEventListInput = ({
+  property,
+  kind,
+  options,
+}: CommonWidgetInputProps<"dateTimeEventList">) => {
+  const t = useWidgetInputTranslation(kind, property);
+  const tEditor = useEventListTranslation(kind);
+  const form = useFormContext();
+  const fieldPath = `options.${property}`;
+  const currentValue = form.values.options[property];
+  const values = Array.isArray(currentValue) ? (currentValue as OptionDateTimeEvent[]) : options.defaultValue;
+  const sensors = useSensors(
+    useSensor(MouseSensor),
+    useSensor(TouchSensor),
+    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates }),
+  );
+
+  useEffect(() => {
+    if (Array.isArray(currentValue)) return;
+    form.setFieldValue(fieldPath, options.defaultValue);
+  }, [currentValue, fieldPath, form, options.defaultValue]);
+
+  const setValues = (nextValues: OptionDateTimeEvent[]) => form.setFieldValue(fieldPath, nextValues);
+  const addEvent = () => {
+    if (values.length >= options.maxValues) return;
+    const localTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+    const target = dayjs().add(1, "day").minute(0).second(0).millisecond(0);
+    setValues([
+      ...values,
+      {
+        id: createId(),
+        label: tEditor("newEvent"),
+        targetUtc: target.toISOString(),
+        timeZone: localTimeZone,
+        recurrence: "none",
+      },
+    ]);
+  };
+
+  return (
+    <Fieldset legend={t("label")}>
+      <Stack gap="sm">
+        {options.withDescription && (
+          <Text size="sm" c="dimmed">
+            {t("description")}
+          </Text>
+        )}
+
+        <Button
+          type="button"
+          variant="light"
+          leftSection={<IconPlus size="var(--mantine-font-size-md)" />}
+          onClick={addEvent}
+          disabled={values.length >= options.maxValues}
+        >
+          {tEditor("add")}
+        </Button>
+
+        <DndContext
+          sensors={sensors}
+          collisionDetection={closestCenter}
+          onDragEnd={({ active, over }) => {
+            if (!over || active.id === over.id) return;
+            const activeIndex = values.findIndex(({ id }) => id === active.id);
+            const overIndex = values.findIndex(({ id }) => id === over.id);
+            if (activeIndex < 0 || overIndex < 0) return;
+            setValues(arrayMove(values, activeIndex, overIndex));
+          }}
+        >
+          <SortableContext items={values.map(({ id }) => id)} strategy={verticalListSortingStrategy}>
+            <Stack gap="xs">
+              {values.map((event) => (
+                <SortableEvent
+                  key={event.id}
+                  kind={kind}
+                  event={event}
+                  timeZoneOptions={options.timeZoneOptions}
+                  onChange={(nextEvent) =>
+                    setValues(values.map((candidate) => (candidate.id === event.id ? nextEvent : candidate)))
+                  }
+                  onRemove={() => setValues(values.filter((candidate) => candidate.id !== event.id))}
+                />
+              ))}
+            </Stack>
+          </SortableContext>
+        </DndContext>
+
+        <Text size="xs" c="dimmed">
+          {tEditor("limit", { count: values.length, maximum: options.maxValues })}
+        </Text>
+      </Stack>
+    </Fieldset>
+  );
+};
+
+interface SortableEventProps {
+  kind: WidgetKind;
+  event: OptionDateTimeEvent;
+  timeZoneOptions: readonly { value: string; label: string }[];
+  onChange: (event: OptionDateTimeEvent) => void;
+  onRemove: () => void;
+}
+
+const SortableEvent = ({ kind, event, timeZoneOptions, onChange, onRemove }: SortableEventProps) => {
+  const t = useEventListTranslation(kind);
+  const { attributes, listeners, setActivatorNodeRef, setNodeRef, transform, transition, isDragging } = useSortable({
+    id: event.id,
+  });
+  const style = {
+    transform: transform ? `translate3d(${Math.round(transform.x)}px, ${Math.round(transform.y)}px, 0)` : undefined,
+    transition,
+    opacity: isDragging ? 0.6 : undefined,
+    zIndex: isDragging ? 1 : undefined,
+  };
+  const hasCurrentTimeZone = timeZoneOptions.some(({ value }) => value === event.timeZone);
+  const selectableTimeZones = hasCurrentTimeZone
+    ? timeZoneOptions
+    : [{ value: event.timeZone, label: t("unsupportedOption", { timeZone: event.timeZone }) }, ...timeZoneOptions];
+  const targetValue = formatWallDateTime(event.targetUtc, event.timeZone);
+  const startValue = event.startUtc ? formatWallDateTime(event.startUtc, event.timeZone) : null;
+
+  const changeTimeZone = (timeZone: string) => {
+    const target = resolveWallDateTimeString(targetValue, timeZone);
+    const start = startValue ? resolveWallDateTimeString(startValue, timeZone) : null;
+    onChange({
+      ...event,
+      timeZone,
+      targetUtc: target?.toISOString() ?? event.targetUtc,
+      startUtc: event.startUtc ? (start?.toISOString() ?? event.startUtc) : undefined,
+    });
+  };
+
+  const updateWallDateTime = (value: string | null, field: "targetUtc" | "startUtc") => {
+    if (!value) return;
+    const resolved = resolveWallDateTimeString(value, event.timeZone);
+    if (!resolved) return;
+    onChange({ ...event, [field]: resolved.toISOString() });
+  };
+
+  return (
+    <Card ref={setNodeRef} withBorder p="sm" style={style}>
+      <Stack gap="xs">
+        <Group gap="xs" wrap="nowrap" align="end">
+          <ActionIcon
+            ref={setActivatorNodeRef}
+            {...attributes}
+            {...listeners}
+            variant="subtle"
+            color="gray"
+            size="lg"
+            aria-label={t("reorder", { event: event.label })}
+            style={{ cursor: "grab" }}
+          >
+            <IconGripVertical size="var(--mantine-font-size-lg)" />
+          </ActionIcon>
+          <TextInput
+            flex={1}
+            label={t("eventLabel")}
+            value={event.label}
+            maxLength={64}
+            onChange={(changeEvent) => onChange({ ...event, label: changeEvent.currentTarget.value })}
+          />
+          <ActionIcon
+            color="red"
+            variant="subtle"
+            size="lg"
+            aria-label={t("remove", { event: event.label })}
+            onClick={onRemove}
+          >
+            <IconTrash size="var(--mantine-font-size-lg)" />
+          </ActionIcon>
+        </Group>
+
+        <Group align="end" grow>
+          <Select
+            label={t("timezone")}
+            searchable
+            data={selectableTimeZones}
+            value={event.timeZone}
+            onChange={(timeZone) => {
+              if (timeZone) changeTimeZone(timeZone);
+            }}
+          />
+          <Select
+            label={t("recurrence")}
+            value={event.recurrence}
+            data={(["none", "yearly"] as const).map((value) => ({ value, label: t(`recurrenceOption.${value}`) }))}
+            onChange={(value) => {
+              if (value) onChange({ ...event, recurrence: value as DateTimeEventRecurrence });
+            }}
+          />
+        </Group>
+
+        <ConfirmedDateTimePicker
+          label={t("target")}
+          value={targetValue || null}
+          onChange={(value) => updateWallDateTime(value, "targetUtc")}
+          confirmLabel={t("confirmDateTime")}
+        />
+
+        {event.recurrence === "none" && (
+          <>
+            <Switch
+              label={t("trackProgress")}
+              checked={event.startUtc !== undefined}
+              onChange={(changeEvent) => {
+                if (!changeEvent.currentTarget.checked) {
+                  const nextEvent = { ...event };
+                  delete nextEvent.startUtc;
+                  onChange(nextEvent);
+                  return;
+                }
+                onChange({ ...event, startUtc: new Date().toISOString() });
+              }}
+            />
+            {event.startUtc && (
+              <ConfirmedDateTimePicker
+                label={t("start")}
+                value={startValue}
+                onChange={(value) => updateWallDateTime(value, "startUtc")}
+                confirmLabel={t("confirmDateTime")}
+              />
+            )}
+          </>
+        )}
+      </Stack>
+    </Card>
+  );
+};
+
+interface ConfirmedDateTimePickerProps {
+  label: string;
+  value: string | null;
+  confirmLabel: string;
+  onChange: (value: string | null) => void;
+}
+
+const ConfirmedDateTimePicker = ({ label, value, confirmLabel, onChange }: ConfirmedDateTimePickerProps) => {
+  const [draftValue, setDraftValue] = useState(value);
+
+  useEffect(() => setDraftValue(value), [value]);
+
+  const resetDraft = () => setDraftValue(value);
+  const confirmDraft = () => {
+    if (!draftValue) return;
+    onChange(draftValue);
+  };
+
+  return (
+    <DateTimePicker
+      label={label}
+      value={draftValue}
+      valueFormat="YYYY-MM-DD HH:mm"
+      timePickerProps={{ withDropdown: true, popoverProps: { withinPortal: false } }}
+      popoverProps={{ withinPortal: true }}
+      submitButtonProps={{ "aria-label": confirmLabel, onClick: confirmDraft }}
+      onChange={setDraftValue}
+      onDropdownClose={resetDraft}
+    />
+  );
+};
+
+type EventListTranslationKey =
+  | "newEvent"
+  | "add"
+  | "remove"
+  | "reorder"
+  | "eventLabel"
+  | "timezone"
+  | "unsupportedOption"
+  | "recurrence"
+  | "recurrenceOption.none"
+  | "recurrenceOption.yearly"
+  | "target"
+  | "trackProgress"
+  | "start"
+  | "confirmDateTime"
+  | "limit";
+
+type EventListTranslation = (key: EventListTranslationKey, values?: Record<string, string | number>) => string;
+
+const useEventListTranslation = (kind: WidgetKind) =>
+  useScopedI18n(`widget.${kind}.dateTimeEventList` as never) as unknown as EventListTranslation;

packages/widgets/src/_inputs/widget-select-input.tsx

@@ -72,6 +72,7 @@ export const WidgetSelectInput = ({ property, kind, options }: CommonWidgetInput
         );
       }}
       description={options.withDescription ? tWidget("description") : undefined}
+      placeholder={options.withPlaceholder ? tWidget("placeholder") : undefined}
       searchable={options.searchable}
       {...inputProps}
     />

packages/widgets/src/_inputs/widget-timezone-list-input.tsx

@@ -0,0 +1,249 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+import {
+  closestCenter,
+  DndContext,
+  KeyboardSensor,
+  MouseSensor,
+  TouchSensor,
+  useSensor,
+  useSensors,
+} from "@dnd-kit/core";
+import {
+  arrayMove,
+  SortableContext,
+  sortableKeyboardCoordinates,
+  useSortable,
+  verticalListSortingStrategy,
+} from "@dnd-kit/sortable";
+import { ActionIcon, Button, Card, Fieldset, Group, Select, Stack, Text, TextInput } from "@mantine/core";
+import { IconGripVertical, IconPlus, IconTrash } from "@tabler/icons-react";
+
+import { createId } from "@homarr/common";
+import type { WidgetKind } from "@homarr/definitions";
+import { useScopedI18n } from "@homarr/translation/client";
+
+import type { OptionTimezone } from "../options";
+import type { CommonWidgetInputProps } from "./common";
+import { useWidgetInputTranslation } from "./common";
+import { useFormContext } from "./form";
+
+export const WidgetTimezoneListInput = ({ property, kind, options }: CommonWidgetInputProps<"timezoneList">) => {
+  const t = useWidgetInputTranslation(kind, property);
+  const tEditor = useTimezoneListTranslation(kind);
+  const form = useFormContext();
+  const fieldPath = `options.${property}`;
+  const currentValue = form.values.options[property];
+  const values = Array.isArray(currentValue) ? (currentValue as OptionTimezone[]) : options.defaultValue;
+  const [selectedTimeZone, setSelectedTimeZone] = useState<string | null>(null);
+  const sensors = useSensors(
+    useSensor(MouseSensor),
+    useSensor(TouchSensor),
+    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates }),
+  );
+
+  useEffect(() => {
+    if (Array.isArray(currentValue)) return;
+    form.setFieldValue(fieldPath, options.defaultValue);
+  }, [currentValue, fieldPath, form, options.defaultValue]);
+
+  const usedTimeZones = useMemo(() => new Set(values.map(({ timeZone }) => timeZone)), [values]);
+  const availableOptions = options.timeZoneOptions.map((option) => ({
+    ...option,
+    disabled: usedTimeZones.has(option.value),
+  }));
+  const isFull = values.length >= options.maxValues;
+
+  const setValues = (nextValues: OptionTimezone[]) => form.setFieldValue(fieldPath, nextValues);
+  const addCity = (city: OptionTimezone) => {
+    if (isFull || usedTimeZones.has(city.timeZone)) return;
+    setValues([...values, city]);
+  };
+  const addSelectedTimeZone = () => {
+    if (!selectedTimeZone) return;
+    const option = options.timeZoneOptions.find(({ value }) => value === selectedTimeZone);
+    if (!option) return;
+    const label = option.label.replace(` (${option.value})`, "");
+    addCity({ id: createId(), label, timeZone: option.value });
+    setSelectedTimeZone(null);
+  };
+
+  return (
+    <Fieldset legend={t("label")}>
+      <Stack gap="sm">
+        {options.withDescription && (
+          <Text size="sm" c="dimmed">
+            {t("description")}
+          </Text>
+        )}
+
+        <Group gap="xs" align="end" wrap="nowrap">
+          <Select
+            flex={1}
+            label={tEditor("timezone")}
+            placeholder={tEditor("searchPlaceholder")}
+            searchable
+            clearable
+            data={availableOptions}
+            value={selectedTimeZone}
+            onChange={setSelectedTimeZone}
+            disabled={isFull}
+            nothingFoundMessage={tEditor("noResults")}
+          />
+          <Button
+            leftSection={<IconPlus size="var(--mantine-font-size-md)" />}
+            onClick={addSelectedTimeZone}
+            disabled={isFull || selectedTimeZone === null}
+          >
+            {tEditor("add")}
+          </Button>
+        </Group>
+
+        <Group gap="xs">
+          {options.presets.map((preset) => (
+            <Button
+              key={preset.timeZone}
+              size="compact-xs"
+              variant="light"
+              disabled={isFull || usedTimeZones.has(preset.timeZone)}
+              onClick={() => addCity({ ...preset, id: createId() })}
+            >
+              {preset.label}
+            </Button>
+          ))}
+        </Group>
+
+        <DndContext
+          sensors={sensors}
+          collisionDetection={closestCenter}
+          onDragEnd={({ active, over }) => {
+            if (!over || active.id === over.id) return;
+            const activeIndex = values.findIndex(({ id }) => id === active.id);
+            const overIndex = values.findIndex(({ id }) => id === over.id);
+            if (activeIndex < 0 || overIndex < 0) return;
+            setValues(arrayMove(values, activeIndex, overIndex));
+          }}
+        >
+          <SortableContext items={values.map(({ id }) => id)} strategy={verticalListSortingStrategy}>
+            <Stack gap="xs">
+              {values.map((city) => (
+                <SortableTimezone
+                  key={city.id}
+                  kind={kind}
+                  city={city}
+                  timeZoneOptions={options.timeZoneOptions}
+                  usedTimeZones={usedTimeZones}
+                  onChange={(nextCity) =>
+                    setValues(values.map((candidate) => (candidate.id === city.id ? nextCity : candidate)))
+                  }
+                  onRemove={() => setValues(values.filter((candidate) => candidate.id !== city.id))}
+                />
+              ))}
+            </Stack>
+          </SortableContext>
+        </DndContext>
+
+        <Text size="xs" c="dimmed">
+          {tEditor("limit", { count: values.length, maximum: options.maxValues })}
+        </Text>
+      </Stack>
+    </Fieldset>
+  );
+};
+
+interface SortableTimezoneProps {
+  kind: WidgetKind;
+  city: OptionTimezone;
+  timeZoneOptions: readonly { value: string; label: string }[];
+  usedTimeZones: ReadonlySet<string>;
+  onChange: (city: OptionTimezone) => void;
+  onRemove: () => void;
+}
+
+const SortableTimezone = ({
+  kind,
+  city,
+  timeZoneOptions,
+  usedTimeZones,
+  onChange,
+  onRemove,
+}: SortableTimezoneProps) => {
+  const t = useTimezoneListTranslation(kind);
+  const { attributes, listeners, setActivatorNodeRef, setNodeRef, transform, transition, isDragging } = useSortable({
+    id: city.id,
+  });
+  const style = {
+    transform: transform ? `translate3d(${Math.round(transform.x)}px, ${Math.round(transform.y)}px, 0)` : undefined,
+    transition,
+    opacity: isDragging ? 0.6 : undefined,
+    zIndex: isDragging ? 1 : undefined,
+  };
+  const hasCurrentTimeZone = timeZoneOptions.some(({ value }) => value === city.timeZone);
+  const selectableTimeZones = hasCurrentTimeZone
+    ? timeZoneOptions
+    : [{ value: city.timeZone, label: t("unsupportedOption", { timeZone: city.timeZone }) }, ...timeZoneOptions];
+
+  return (
+    <Card ref={setNodeRef} withBorder p="xs" style={style}>
+      <Group gap="xs" wrap="wrap" align="end">
+        <ActionIcon
+          ref={setActivatorNodeRef}
+          {...attributes}
+          {...listeners}
+          variant="subtle"
+          color="gray"
+          size="lg"
+          aria-label={t("reorder", { city: city.label })}
+          style={{ cursor: "grab" }}
+        >
+          <IconGripVertical size="var(--mantine-font-size-lg)" />
+        </ActionIcon>
+        <TextInput
+          flex={1}
+          label={t("cityLabel")}
+          value={city.label}
+          onChange={(event) => onChange({ ...city, label: event.currentTarget.value })}
+        />
+        <Select
+          flex={2}
+          label={t("timezone")}
+          searchable
+          data={selectableTimeZones.map((option) => ({
+            ...option,
+            disabled: option.value !== city.timeZone && usedTimeZones.has(option.value),
+          }))}
+          value={city.timeZone}
+          onChange={(timeZone) => {
+            if (timeZone) onChange({ ...city, timeZone });
+          }}
+        />
+        <ActionIcon
+          color="red"
+          variant="subtle"
+          size="lg"
+          aria-label={t("remove", { city: city.label })}
+          onClick={onRemove}
+        >
+          <IconTrash size="var(--mantine-font-size-lg)" />
+        </ActionIcon>
+      </Group>
+    </Card>
+  );
+};
+
+type TimezoneListTranslationKey =
+  | "timezone"
+  | "cityLabel"
+  | "searchPlaceholder"
+  | "noResults"
+  | "unsupportedOption"
+  | "add"
+  | "remove"
+  | "reorder"
+  | "limit";
+
+type TimezoneListTranslation = (key: TimezoneListTranslationKey, values?: Record<string, string | number>) => string;
+
+const useTimezoneListTranslation = (kind: WidgetKind) =>
+  useScopedI18n(`widget.${kind}.timezoneList` as never) as unknown as TimezoneListTranslation;

packages/widgets/src/air-quality/component.tsx

@@ -0,0 +1,399 @@
+"use client";
+
+import { useId } from "react";
+import { CompositeChart, Sparkline } from "@mantine/charts";
+import { Box, Group, Paper, ScrollArea, SimpleGrid, Stack, Text, VisuallyHidden } from "@mantine/core";
+import { IconMapPin } from "@tabler/icons-react";
+
+import { clientApi } from "@homarr/api/client";
+import { useCurrentIntlLocale, useScopedI18n } from "@homarr/translation/client";
+
+import { WidgetEmptyState } from "../common/empty-state";
+import { formatLocalizedDate, formatLocalizedTime } from "../common/locale";
+import { getUsableWidgetQueryData, isInitialWidgetQueryPending } from "../common/query-state";
+import { WidgetQueryErrorIndicator, WidgetQueryLoadingState } from "../common/query-state-indicator";
+import type { WidgetComponentProps } from "../definition";
+import type { AirQualityData, PollutantKey, PollenKey } from "./display";
+import {
+  getAqiCategory,
+  getAqiColor,
+  getAqiStandard,
+  getAqiValue,
+  getCompactAirQualityLayout,
+  getDailyAqiValue,
+  getDominantPollutant,
+  getStrongestPollen,
+  getUpcomingHours,
+  getUvCategory,
+} from "./display";
+
+export default function AirQualityWidget({ options, width, height, displayMode }: WidgetComponentProps<"airQuality">) {
+  const t = useScopedI18n("widget.airQuality");
+  const query = clientApi.widget.airQuality.atLocation.useQuery({
+    latitude: options.location.latitude,
+    longitude: options.location.longitude,
+  });
+  const airQuality = getUsableWidgetQueryData(query);
+
+  if (isInitialWidgetQueryPending(query)) return <WidgetQueryLoadingState />;
+  if (!airQuality) return <WidgetEmptyState />;
+
+  return (
+    <Box h="100%" w="100%" pos="relative">
+      {displayMode === "advanced" ? (
+        <AdvancedAirQuality airQuality={airQuality} options={options} width={width} />
+      ) : (
+        <CompactAirQuality airQuality={airQuality} height={height} options={options} width={width} />
+      )}
+      {query.error && (
+        <Box pos="absolute" top={4} right={4}>
+          <WidgetQueryErrorIndicator error={query.error} label={t("name")} />
+        </Box>
+      )}
+    </Box>
+  );
+}
+
+interface AirQualityViewProps {
+  airQuality: AirQualityData;
+  options: WidgetComponentProps<"airQuality">["options"];
+}
+
+const CompactAirQuality = ({
+  airQuality,
+  height,
+  options,
+  width,
+}: AirQualityViewProps & { height: number; width: number }) => {
+  const locale = useCurrentIntlLocale();
+  const t = useScopedI18n("widget.airQuality");
+  const layout = getCompactAirQualityLayout(width, height);
+  const standard = getAqiStandard(options.aqiStandard, locale);
+  const value = getAqiValue(airQuality.current, standard);
+  const category = getAqiCategory(value, standard);
+  const dominant = getDominantPollutant(airQuality.current, standard);
+  const strongestPollen = getStrongestPollen(airQuality.current);
+  const labels = useAirQualityLabels();
+  const sixHours = getUpcomingHours(airQuality, 6)
+    .map((hour) => getAqiValue(hour, standard))
+    .filter((hour): hour is number => hour !== null);
+
+  return (
+    <Stack
+      h="100%"
+      w="100%"
+      justify="center"
+      align="center"
+      gap={layout.tiny ? 2 : "xs"}
+      p="xs"
+      style={{ overflow: "hidden" }}
+    >
+      <Group gap="xs" wrap="nowrap" align="center">
+        <Text fz={layout.tiny ? 34 : 42} fw={700} lh={1} c={getAqiColor(category)}>
+          {formatAqi(value, locale)}
+        </Text>
+        <Stack gap={1} align="flex-start">
+          <Text size={layout.tiny ? "xs" : "sm"} fw={600}>
+            {t(`category.${category}`)}
+          </Text>
+        </Stack>
+      </Group>
+
+      {!layout.tiny && (
+        <Group gap="md" justify="center" wrap="wrap">
+          {options.showUv && (
+            <MetricLine
+              label={t("uv.label")}
+              value={`${formatDecimal(airQuality.current.uvIndex, locale)} · ${t(`uv.category.${getUvCategory(airQuality.current.uvIndex)}`)}`}
+            />
+          )}
+          {options.showPollutants && dominant && (
+            <MetricLine label={t("dominantPollutant")} value={labels.pollutants[dominant.key]} />
+          )}
+        </Group>
+      )}
+
+      {!layout.tiny && layout.showParticulatesAndPollen && (
+        <Group gap="md" justify="center" wrap="wrap">
+          {options.showPollutants && (
+            <>
+              <MetricLine
+                label={labels.pollutants.pm2_5}
+                value={formatConcentration(airQuality.current.pollutants.pm2_5, locale, t)}
+              />
+              <MetricLine
+                label={labels.pollutants.pm10}
+                value={formatConcentration(airQuality.current.pollutants.pm10, locale, t)}
+              />
+            </>
+          )}
+          {options.showPollen && strongestPollen && (
+            <MetricLine
+              label={t("strongestPollen")}
+              value={`${labels.pollen[strongestPollen.key]} · ${formatPollen(strongestPollen.value, locale, t)}`}
+            />
+          )}
+        </Group>
+      )}
+
+      {!layout.tiny && layout.showSparkline && sixHours.length > 1 && (
+        <Box component="figure" w="100%" h={34} m={0}>
+          <Sparkline
+            aria-hidden
+            h="100%"
+            w="100%"
+            data={sixHours}
+            color={getAqiColor(category)}
+            curveType="monotone"
+            fillOpacity={0.2}
+            strokeWidth={2}
+          />
+          <VisuallyHidden component="figcaption">{t("compact.sixHourTrend")}</VisuallyHidden>
+        </Box>
+      )}
+    </Stack>
+  );
+};
+
+const AdvancedAirQuality = ({ airQuality, options, width }: AirQualityViewProps & { width: number }) => {
+  const chartId = useId();
+  const locale = useCurrentIntlLocale();
+  const t = useScopedI18n("widget.airQuality");
+  const standard = getAqiStandard(options.aqiStandard, locale);
+  const value = getAqiValue(airQuality.current, standard);
+  const category = getAqiCategory(value, standard);
+  const labels = useAirQualityLabels();
+  const upcoming = getUpcomingHours(airQuality, 24);
+  const chartData = upcoming.map((hour) => ({
+    observedAt: hour.observedAt,
+    aqi: getAqiValue(hour, standard) ?? Number.NaN,
+    uv: hour.uvIndex ?? Number.NaN,
+  }));
+  const series = [
+    { name: "aqi", label: t("aqiLabel"), color: getAqiColor(category), type: "line" as const },
+    ...(options.showUv
+      ? [{ name: "uv", label: t("uv.label"), color: "yellow.7", type: "line" as const, yAxisId: "right" as const }]
+      : []),
+  ];
+
+  return (
+    <ScrollArea h="100%" w="100%" type="auto" offsetScrollbars scrollbarSize={6}>
+      <Stack gap="md" p="md">
+        <Group justify="space-between" align="flex-start" wrap="wrap">
+          <Stack gap={2}>
+            <Text fz={38} fw={700} lh={1} c={getAqiColor(category)}>
+              {formatAqi(value, locale)}
+            </Text>
+            <Text fw={600}>{t(`category.${category}`)}</Text>
+          </Stack>
+          <Stack gap={2} align="flex-end">
+            <Group gap={5} wrap="nowrap">
+              <IconMapPin size="var(--mantine-font-size-md)" aria-hidden />
+              <Text size="sm" fw={600}>
+                {options.location.name}
+              </Text>
+            </Group>
+            <Text size="xs" c="dimmed">
+              {t("advanced.observedAt", {
+                time: formatLocalizedTime(airQuality.current.observedAt, locale, { timeZone: airQuality.timezone }),
+              })}
+            </Text>
+          </Stack>
+        </Group>
+
+        <SimpleGrid cols={{ base: 2, sm: 4 }} spacing="xs">
+          <MetricCard label={t("aqiLabel")} value={formatAqi(value, locale)} />
+          {options.showUv && (
+            <MetricCard label={t("uv.label")} value={formatDecimal(airQuality.current.uvIndex, locale)} />
+          )}
+          {options.showPollutants && (
+            <>
+              <MetricCard
+                label={labels.pollutants.pm2_5}
+                value={formatConcentration(airQuality.current.pollutants.pm2_5, locale, t)}
+              />
+              <MetricCard
+                label={labels.pollutants.pm10}
+                value={formatConcentration(airQuality.current.pollutants.pm10, locale, t)}
+              />
+            </>
+          )}
+        </SimpleGrid>
+
+        <SimpleGrid cols={width >= 800 ? 2 : 1} spacing="md">
+          <Paper withBorder p="sm">
+            <Text id={chartId} size="sm" fw={600} mb="xs">
+              {t("advanced.next24Hours")}
+            </Text>
+            {chartData.length > 0 ? (
+              <>
+                <Box aria-hidden>
+                  <CompositeChart
+                    h={220}
+                    data={chartData}
+                    dataKey="observedAt"
+                    series={series}
+                    curveType="monotone"
+                    gridAxis="y"
+                    tickLine="none"
+                    withDots={false}
+                    withLegend
+                    withRightYAxis={options.showUv}
+                    rightYAxisProps={{ width: 34 }}
+                    xAxisProps={{
+                      tickFormatter: (time: string) =>
+                        formatLocalizedTime(time, locale, { timeZone: airQuality.timezone }),
+                    }}
+                  />
+                </Box>
+                <VisuallyHidden>
+                  <ul aria-labelledby={chartId}>
+                    {upcoming.map((hour) => (
+                      <li key={hour.observedAt}>
+                        {formatLocalizedTime(hour.observedAt, locale, { timeZone: airQuality.timezone })}:{" "}
+                        {t("advanced.aqiValue", {
+                          value: formatAqi(getAqiValue(hour, standard), locale),
+                        })}
+                        {options.showUv
+                          ? `, ${t("advanced.uvValue", { value: formatDecimal(hour.uvIndex, locale) })}`
+                          : ""}
+                      </li>
+                    ))}
+                  </ul>
+                </VisuallyHidden>
+              </>
+            ) : (
+              <Text size="sm" c="dimmed">
+                {t("advanced.noForecast")}
+              </Text>
+            )}
+          </Paper>
+
+          <Stack gap="md">
+            {options.showPollutants && (
+              <Paper withBorder p="sm">
+                <Text size="sm" fw={600} mb="xs">
+                  {t("advanced.pollutants")}
+                </Text>
+                <SimpleGrid cols={2} spacing="xs">
+                  {pollutantKeys.map((key) => (
+                    <MetricLine
+                      key={key}
+                      label={labels.pollutants[key]}
+                      value={formatConcentration(airQuality.current.pollutants[key], locale, t)}
+                    />
+                  ))}
+                </SimpleGrid>
+              </Paper>
+            )}
+
+            {options.showPollen && hasAvailableValue(airQuality.current.pollen) && (
+              <Paper withBorder p="sm">
+                <Text size="sm" fw={600} mb="xs">
+                  {t("advanced.pollen")}
+                </Text>
+                <SimpleGrid cols={2} spacing="xs">
+                  {pollenKeys.map((key) => {
+                    const pollen = airQuality.current.pollen[key];
+                    if (pollen === null) return null;
+                    return <MetricLine key={key} label={labels.pollen[key]} value={formatPollen(pollen, locale, t)} />;
+                  })}
+                </SimpleGrid>
+              </Paper>
+            )}
+          </Stack>
+        </SimpleGrid>
+
+        <Paper withBorder p="sm">
+          <Text size="sm" fw={600} mb="xs">
+            {t("advanced.sevenDayForecast")}
+          </Text>
+          <SimpleGrid cols={{ base: 2, sm: 4, md: 7 }} spacing="xs">
+            {airQuality.daily.map((day) => {
+              const dailyAqi = getDailyAqiValue(day, standard);
+              return (
+                <Stack key={day.date} gap={2} align="center">
+                  <Text size="xs" c="dimmed">
+                    {formatLocalizedDate(day.date, locale, { weekday: "short" })}
+                  </Text>
+                  <Text fw={700} c={getAqiColor(getAqiCategory(dailyAqi, standard))}>
+                    {formatAqi(dailyAqi, locale)}
+                  </Text>
+                  {options.showUv && (
+                    <Text size="xs">{t("advanced.uvShort", { value: formatDecimal(day.uvIndexMax, locale) })}</Text>
+                  )}
+                </Stack>
+              );
+            })}
+          </SimpleGrid>
+        </Paper>
+      </Stack>
+    </ScrollArea>
+  );
+};
+
+const MetricCard = ({ label, value }: { label: string; value: string }) => (
+  <Paper withBorder p="xs">
+    <Text size="xs" c="dimmed">
+      {label}
+    </Text>
+    <Text fz="lg" fw={700}>
+      {value}
+    </Text>
+  </Paper>
+);
+
+const MetricLine = ({ label, value }: { label: string; value: string }) => (
+  <Stack gap={0} miw={0}>
+    <Text size="xs" c="dimmed" truncate>
+      {label}
+    </Text>
+    <Text size="sm" fw={600} truncate>
+      {value}
+    </Text>
+  </Stack>
+);
+
+const pollutantKeys: PollutantKey[] = ["pm2_5", "pm10", "ozone", "nitrogenDioxide", "sulphurDioxide", "carbonMonoxide"];
+const pollenKeys: PollenKey[] = ["alder", "birch", "grass", "mugwort", "olive", "ragweed"];
+
+const useAirQualityLabels = () => {
+  const t = useScopedI18n("widget.airQuality");
+  return {
+    pollutants: {
+      pm2_5: t("pollutant.pm2_5"),
+      pm10: t("pollutant.pm10"),
+      ozone: t("pollutant.ozone"),
+      nitrogenDioxide: t("pollutant.nitrogenDioxide"),
+      sulphurDioxide: t("pollutant.sulphurDioxide"),
+      carbonMonoxide: t("pollutant.carbonMonoxide"),
+    } satisfies Record<PollutantKey, string>,
+    pollen: {
+      alder: t("pollen.alder"),
+      birch: t("pollen.birch"),
+      grass: t("pollen.grass"),
+      mugwort: t("pollen.mugwort"),
+      olive: t("pollen.olive"),
+      ragweed: t("pollen.ragweed"),
+    } satisfies Record<PollenKey, string>,
+  };
+};
+
+const formatAqi = (value: number | null, locale: string) => {
+  if (value === null) return "—";
+  return new Intl.NumberFormat(locale, { maximumFractionDigits: 0 }).format(value);
+};
+
+const formatDecimal = (value: number | null, locale: string) => {
+  if (value === null) return "—";
+  return new Intl.NumberFormat(locale, { maximumFractionDigits: 1 }).format(value);
+};
+
+type ScopedAirQualityTranslator = ReturnType<typeof useScopedI18n<"widget.airQuality">>;
+
+const formatConcentration = (value: number | null, locale: string, t: ScopedAirQualityTranslator) =>
+  t("unit.concentration", { value: formatDecimal(value, locale) });
+const formatPollen = (value: number | null, locale: string, t: ScopedAirQualityTranslator) =>
+  t("unit.pollen", { value: formatDecimal(value, locale) });
+const hasAvailableValue = (values: Record<string, number | null>) =>
+  Object.values(values).some((value) => value !== null);

packages/widgets/src/air-quality/display.spec.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  getAqiCategory,
+  getAqiStandard,
+  getCompactAirQualityLayout,
+  getDominantPollutant,
+  getStrongestPollen,
+} from "./display";
+
+const point = {
+  observedAt: "2026-07-01T10:00:00.000Z",
+  europeanAqi: 42,
+  usAqi: 60,
+  uvIndex: 4,
+  pollutants: { pm2_5: 12, pm10: 20, ozone: 30, nitrogenDioxide: 4, sulphurDioxide: 3, carbonMonoxide: 100 },
+  europeanSubIndices: {
+    pm2_5: 20,
+    pm10: 31,
+    ozone: 42,
+    nitrogenDioxide: 10,
+    sulphurDioxide: 5,
+    carbonMonoxide: null,
+  },
+  usSubIndices: {
+    pm2_5: 50,
+    pm10: 40,
+    ozone: 30,
+    nitrogenDioxide: 20,
+    sulphurDioxide: 10,
+    carbonMonoxide: 60,
+  },
+  pollen: { alder: null, birch: 12, grass: 20, mugwort: 5, olive: null, ragweed: 2 },
+};
+
+describe("air quality display", () => {
+  it("uses the US scale only for US locales in automatic mode", () => {
+    expect(getAqiStandard("auto", "en-US")).toBe("us");
+    expect(getAqiStandard("auto", "fr-FR")).toBe("european");
+    expect(getAqiStandard("auto", "en")).toBe("european");
+    expect(getAqiStandard("us", "fr-FR")).toBe("us");
+  });
+
+  it("uses the defined AQI band boundaries", () => {
+    expect(getAqiCategory(20, "european")).toBe("good");
+    expect(getAqiCategory(21, "european")).toBe("fair");
+    expect(getAqiCategory(101, "european")).toBe("extremelyPoor");
+    expect(getAqiCategory(50, "us")).toBe("good");
+    expect(getAqiCategory(51, "us")).toBe("moderate");
+    expect(getAqiCategory(301, "us")).toBe("hazardous");
+  });
+
+  it("finds dominant subindices and raw pollen without combining them", () => {
+    expect(getDominantPollutant(point, "european")).toEqual({ key: "ozone", value: 42 });
+    expect(getDominantPollutant(point, "us")).toEqual({ key: "carbonMonoxide", value: 60 });
+    expect(getStrongestPollen(point)).toEqual({ key: "grass", value: 20 });
+  });
+
+  it("progressively reveals compact details", () => {
+    expect(getCompactAirQualityLayout(149, 200)).toMatchObject({ tiny: true });
+    expect(getCompactAirQualityLayout(250, 150)).toMatchObject({ showParticulatesAndPollen: true });
+    expect(getCompactAirQualityLayout(300, 170)).toMatchObject({ showSparkline: true });
+  });
+});

packages/widgets/src/air-quality/display.ts

@@ -0,0 +1,144 @@
+export interface AirQualityPollutants {
+  pm2_5: number | null;
+  pm10: number | null;
+  ozone: number | null;
+  nitrogenDioxide: number | null;
+  sulphurDioxide: number | null;
+  carbonMonoxide: number | null;
+}
+
+export interface AirQualityPoint {
+  observedAt: string;
+  europeanAqi: number | null;
+  usAqi: number | null;
+  uvIndex: number | null;
+  pollutants: AirQualityPollutants;
+  europeanSubIndices: AirQualityPollutants;
+  usSubIndices: AirQualityPollutants;
+  pollen: Record<"alder" | "birch" | "grass" | "mugwort" | "olive" | "ragweed", number | null>;
+}
+
+export interface AirQualityData {
+  timezone: string;
+  utcOffsetSeconds: number;
+  current: AirQualityPoint;
+  hourly: AirQualityPoint[];
+  daily: {
+    date: string;
+    europeanAqiMax: number | null;
+    usAqiMax: number | null;
+    uvIndexMax: number | null;
+    pm2_5Max: number | null;
+    pm10Max: number | null;
+  }[];
+}
+
+export type AqiStandard = "european" | "us";
+export type AqiStandardOption = "auto" | AqiStandard;
+export type AqiCategory =
+  | "good"
+  | "fair"
+  | "moderate"
+  | "unhealthySensitive"
+  | "unhealthy"
+  | "poor"
+  | "veryPoor"
+  | "veryUnhealthy"
+  | "extremelyPoor"
+  | "hazardous"
+  | "unknown";
+export type UvCategory = "low" | "moderate" | "high" | "veryHigh" | "extreme" | "unknown";
+export type PollutantKey = keyof AirQualityPoint["pollutants"];
+export type PollenKey = keyof AirQualityPoint["pollen"];
+
+export const getAqiStandard = (option: AqiStandardOption, locale: string): AqiStandard => {
+  if (option !== "auto") return option;
+  try {
+    return new Intl.Locale(locale).region === "US" ? "us" : "european";
+  } catch {
+    return "european";
+  }
+};
+
+export const getAqiValue = (point: AirQualityPoint, standard: AqiStandard): number | null => {
+  if (standard === "us") return point.usAqi;
+  return point.europeanAqi;
+};
+
+export const getDailyAqiValue = (day: AirQualityData["daily"][number], standard: AqiStandard): number | null => {
+  if (standard === "us") return day.usAqiMax;
+  return day.europeanAqiMax;
+};
+
+export const getAqiCategory = (value: number | null, standard: AqiStandard): AqiCategory => {
+  if (value === null) return "unknown";
+
+  if (standard === "us") {
+    if (value <= 50) return "good";
+    if (value <= 100) return "moderate";
+    if (value <= 150) return "unhealthySensitive";
+    if (value <= 200) return "unhealthy";
+    if (value <= 300) return "veryUnhealthy";
+    return "hazardous";
+  }
+
+  if (value <= 20) return "good";
+  if (value <= 40) return "fair";
+  if (value <= 60) return "moderate";
+  if (value <= 80) return "poor";
+  if (value <= 100) return "veryPoor";
+  return "extremelyPoor";
+};
+
+export const getAqiColor = (category: AqiCategory): string => {
+  if (category === "good") return "green.6";
+  if (category === "fair") return "lime.7";
+  if (category === "moderate") return "yellow.7";
+  if (category === "unhealthySensitive" || category === "poor") return "orange.7";
+  if (category === "unhealthy" || category === "veryPoor") return "red.7";
+  if (category === "veryUnhealthy" || category === "extremelyPoor") return "grape.7";
+  if (category === "hazardous") return "dark.6";
+  return "gray.6";
+};
+
+export const getUvCategory = (value: number | null): UvCategory => {
+  if (value === null) return "unknown";
+  if (value < 3) return "low";
+  if (value < 6) return "moderate";
+  if (value < 8) return "high";
+  if (value < 11) return "veryHigh";
+  return "extreme";
+};
+
+export const getDominantPollutant = (
+  point: AirQualityPoint,
+  standard: AqiStandard,
+): { key: PollutantKey; value: number } | null => {
+  const values = standard === "us" ? point.usSubIndices : point.europeanSubIndices;
+  return getHighestValue(values);
+};
+
+export const getStrongestPollen = (point: AirQualityPoint): { key: PollenKey; value: number } | null =>
+  getHighestValue(point.pollen);
+
+const getHighestValue = <TKey extends string>(
+  values: Record<TKey, number | null>,
+): { key: TKey; value: number } | null => {
+  let highest: { key: TKey; value: number } | null = null;
+  for (const [key, value] of Object.entries(values) as [TKey, number | null][]) {
+    if (value === null) continue;
+    if (highest === null || value > highest.value) highest = { key, value };
+  }
+  return highest;
+};
+
+export const getCompactAirQualityLayout = (width: number, height: number) => ({
+  tiny: width < 150 || height < 96,
+  showParticulatesAndPollen: width >= 240 && height >= 140,
+  showSparkline: width >= 300 && height >= 170,
+});
+
+export const getUpcomingHours = (data: AirQualityData, count: number): AirQualityData["hourly"] => {
+  const currentTime = Date.parse(data.current.observedAt);
+  return data.hourly.filter((hour) => Date.parse(hour.observedAt) >= currentTime).slice(0, count);
+};

packages/widgets/src/air-quality/index.ts

@@ -0,0 +1,43 @@
+import { IconWind } from "@tabler/icons-react";
+
+import { createWidgetDefinition, widgetQueryInputMatches } from "../definition";
+import { optionsBuilder } from "../options";
+
+export const { definition, componentLoader } = createWidgetDefinition("airQuality", {
+  icon: IconWind,
+  supportsAdvancedFocus: true,
+  queryKey: [["widget", "airQuality", "atLocation"]],
+  refetchInterval: 900,
+  queryMatcher: ({ input }, scope) => {
+    const location = scope.options.location;
+    if (location === null || typeof location !== "object" || !("latitude" in location) || !("longitude" in location)) {
+      return false;
+    }
+    return widgetQueryInputMatches(input, {
+      latitude: location.latitude,
+      longitude: location.longitude,
+    });
+  },
+  createOptions() {
+    return optionsBuilder.from((factory) => ({
+      location: factory.location({
+        defaultValue: {
+          name: "Paris",
+          latitude: 48.85341,
+          longitude: 2.3488,
+        },
+      }),
+      aqiStandard: factory.select({
+        defaultValue: "auto",
+        options: [
+          { value: "auto", label: (t) => t("widget.airQuality.option.aqiStandard.options.auto") },
+          { value: "european", label: (t) => t("widget.airQuality.option.aqiStandard.options.european") },
+          { value: "us", label: (t) => t("widget.airQuality.option.aqiStandard.options.us") },
+        ],
+      }),
+      showUv: factory.switch({ defaultValue: true }),
+      showPollutants: factory.switch({ defaultValue: true }),
+      showPollen: factory.switch({ defaultValue: true }),
+    }));
+  },
+}).withDynamicImport(() => import("./component"));

packages/widgets/src/catalog.ts

@@ -15,15 +15,18 @@ import {
   IconBuildingBank,
   IconBusStop,
   IconCalendar,
+  IconCalendarWeek,
   IconChartAreaLine,
   IconChartBar,
   IconClock,
+  IconClockPlay,
   IconCloud,
   IconDeviceCctv,
   IconDeviceGamepad,
   IconDownload,
   IconFileText,
   IconGraphFilled,
+  IconHourglass,
   IconHeadphones,
   IconHeartRateMonitor,
   IconHeartbeat,
@@ -47,6 +50,7 @@ import {
   IconTransform,
   IconVideo,
   IconWall,
+  IconWind,
   IconZoomQuestion,
 } from "@tabler/icons-react";
 
@@ -56,6 +60,10 @@ import type { TablerIcon } from "@homarr/ui";
 export const widgetCatalogIcons: Record<WidgetKind, TablerIcon> = {
   clock: IconClock,
   weather: IconCloud,
+  today: IconCalendarWeek,
+  airQuality: IconWind,
+  countdown: IconHourglass,
+  timer: IconClockPlay,
   app: IconApps,
   assistant: IconRobot,
   iframe: IconBrowser,

packages/widgets/src/clock/advanced-view.tsx

@@ -0,0 +1,329 @@
+import {
+  Alert,
+  Badge,
+  Box,
+  Divider,
+  Group,
+  Paper,
+  ScrollArea,
+  SimpleGrid,
+  Stack,
+  Text,
+  ThemeIcon,
+  Title,
+} from "@mantine/core";
+import { IconAlertTriangle, IconClock } from "@tabler/icons-react";
+import type { Dayjs } from "dayjs";
+
+import { useCurrentIntlLocale, useScopedI18n } from "@homarr/translation/client";
+
+import { formatLocalizedDate, formatLocalizedTime } from "../common/locale";
+import type { WidgetComponentProps } from "../definition";
+import { clockTimeFormatShowsSeconds, clockTimeFormatUses12Hours, resolveClockTimeFormat } from "./format";
+import { TimeOfDayBar } from "./time-of-day-bar";
+import { ClockWeatherSummary } from "./weather-summary";
+import {
+  createWorldClockTime,
+  formatRelativeOffset,
+  formatUtcOffset,
+  getTimeOfDayPhase,
+  humanizeTimeZone,
+  maximumWorldClockCities,
+} from "./world-clock";
+import type { TimeOfDayPhase, WorldClockTime } from "./world-clock";
+
+interface AdvancedClockViewProps {
+  now: Date;
+  options: WidgetComponentProps<"clock">["options"];
+  primaryTime: Dayjs;
+  primaryTimeZone: string;
+  primaryTimeZoneInvalid: boolean;
+}
+
+export const AdvancedClockView = ({
+  now,
+  options,
+  primaryTime,
+  primaryTimeZone,
+  primaryTimeZoneInvalid,
+}: AdvancedClockViewProps) => {
+  const t = useScopedI18n("widget.clock");
+  const primaryLabel = getPrimaryLabel(options, t);
+  const primary: WorldClockTime = {
+    id: "primary",
+    label: primaryLabel,
+    timeZone: primaryTimeZone,
+    zonedTime: primaryTime,
+    phase: getTimeOfDayPhase(primaryTime.hour()),
+    minuteOfDay: primaryTime.hour() * 60 + primaryTime.minute() + primaryTime.second() / 60,
+    utcOffset: primaryTime.utcOffset(),
+    dayDifference: 0,
+  };
+  const cities = options.worldClockCities
+    .slice(0, maximumWorldClockCities)
+    .filter(({ timeZone }) => timeZone !== primaryTimeZone)
+    .map((city) => createWorldClockTime({ city, now, primaryTime }));
+
+  return (
+    <ScrollArea
+      h="100%"
+      w="100%"
+      type="auto"
+      offsetScrollbars
+      scrollbarSize={6}
+      aria-label={t("worldClock.advancedLabel")}
+    >
+      <Stack gap="md" p={{ base: "sm", sm: "md" }}>
+        {primaryTimeZoneInvalid && (
+          <Alert icon={<IconAlertTriangle />} color="yellow" title={t("worldClock.unsupportedPrimaryTitle")}>
+            {t("worldClock.unsupportedPrimary", { timeZone: options.timezone })}
+          </Alert>
+        )}
+        <PrimaryClock now={now} options={options} primary={primary} />
+        <OverviewMode now={now} options={options} primary={primary} cities={cities} />
+      </Stack>
+    </ScrollArea>
+  );
+};
+
+interface ModeProps {
+  now: Date;
+  options: WidgetComponentProps<"clock">["options"];
+  primary: WorldClockTime;
+  cities: WorldClockTime[];
+}
+
+const PrimaryClock = ({ now, options, primary }: Pick<ModeProps, "now" | "options" | "primary">) => {
+  const locale = useCurrentIntlLocale();
+  const t = useScopedI18n("widget.clock");
+  const primaryTime = primary.zonedTime;
+  if (!primaryTime || primary.phase === null || primary.minuteOfDay === null) return null;
+
+  return (
+    <Paper withBorder radius="md" p="md">
+      <Group justify="space-between" align="flex-start" gap="lg" wrap="wrap">
+        <Stack gap={5} miw={0}>
+          <Group gap="xs" wrap="nowrap">
+            <ThemeIcon color={getPhaseColor(primary.phase)} variant="light" radius="xl" size="md">
+              <IconClock size={16} />
+            </ThemeIcon>
+            <Title order={2} size="h4" fw={600}>
+              {primary.label}
+            </Title>
+          </Group>
+          <ClockTime entry={primary} now={now} options={options} primary />
+          {options.showDate && (
+            <Text size="sm" c="dimmed">
+              {formatLocalizedDate(now, locale, { dateStyle: "full", timeZone: primary.timeZone })}
+            </Text>
+          )}
+          <Group gap="xs" wrap="wrap">
+            <Badge color="gray" variant="light" tt="none">
+              {primary.timeZone}
+            </Badge>
+            <Badge color="gray" variant="outline" tt="none">
+              {formatUtcOffset(primaryTime.utcOffset())}
+            </Badge>
+          </Group>
+        </Stack>
+        {options.showWeather && (
+          <Paper withBorder radius="md" p="sm">
+            <ClockWeatherSummary
+              latitude={options.weatherLocation.latitude}
+              longitude={options.weatherLocation.longitude}
+              locationName={options.weatherLocation.name}
+              isFahrenheit={options.isWeatherFormatFahrenheit}
+              animateIcon={options.animateWeatherIcon}
+              detailed
+            />
+          </Paper>
+        )}
+      </Group>
+      <Divider my="sm" />
+      <TimeOfDayBar
+        minuteOfDay={primary.minuteOfDay}
+        phase={primary.phase}
+        showLegend
+        showTicks
+        label={t("worldClock.timeBarLabel", { city: primary.label })}
+      />
+    </Paper>
+  );
+};
+
+const OverviewMode = ({ now, options, primary, cities }: ModeProps) => {
+  const t = useScopedI18n("widget.clock");
+  if (cities.length === 0) return <EmptyCities />;
+
+  return (
+    <Stack gap="xs">
+      <Group justify="space-between" align="baseline">
+        <Title order={3} size="h5">
+          {t("worldClock.cities")}
+        </Title>
+        <Text size="xs" c="dimmed">
+          {t("worldClock.cityCount", { count: cities.length })}
+        </Text>
+      </Group>
+      <SimpleGrid component="ul" cols={{ base: 1, sm: 2 }} spacing="sm" p={0} m={0} style={{ listStyle: "none" }}>
+        {cities.map((city) => (
+          <WorldClockCard
+            key={city.id}
+            entry={city}
+            now={now}
+            options={options}
+            primaryOffset={primary.utcOffset ?? 0}
+          />
+        ))}
+      </SimpleGrid>
+    </Stack>
+  );
+};
+
+interface ClockEntryProps {
+  entry: WorldClockTime;
+  now: Date;
+  options: WidgetComponentProps<"clock">["options"];
+  primaryOffset: number;
+}
+
+const WorldClockCard = ({ entry, now, options, primaryOffset }: ClockEntryProps) => {
+  if (!entry.zonedTime || entry.utcOffset === null) {
+    return <InvalidTimeZone entry={entry} />;
+  }
+
+  return (
+    <Paper component="li" withBorder radius="md" p="md">
+      <Stack gap="sm">
+        <Stack gap={0} miw={0}>
+          <Text fw={600} truncate>
+            {entry.label}
+          </Text>
+          <Text size="xs" c="dimmed" truncate>
+            {entry.timeZone}
+          </Text>
+        </Stack>
+        <ClockTime entry={entry} now={now} options={options} compact />
+        <DayAndOffset entry={entry} now={now} primaryOffset={primaryOffset} />
+      </Stack>
+    </Paper>
+  );
+};
+
+const ClockTime = ({
+  entry,
+  now,
+  options,
+  primary = false,
+  compact = false,
+}: Omit<ClockEntryProps, "primaryOffset"> & { primary?: boolean; compact?: boolean }) => {
+  const locale = useCurrentIntlLocale();
+  const t = useScopedI18n("widget.clock");
+  if (!entry.zonedTime) return null;
+  let formattedTime = formatLocalizedTime(now, locale, {
+    hour12: clockTimeFormatUses12Hours(options.customTimeFormat, options.is24HourFormat),
+    includeSeconds: clockTimeFormatShowsSeconds(options.customTimeFormat),
+    timeZone: entry.timeZone,
+  });
+  if (primary) {
+    formattedTime = entry.zonedTime.format(resolveClockTimeFormat(options.customTimeFormat, options.is24HourFormat));
+  }
+  const accessibleDate = formatLocalizedDate(now, locale, {
+    dateStyle: "medium",
+    timeZone: entry.timeZone,
+  });
+  const fontSize = compact ? { base: 30, sm: 34 } : { base: 44, sm: 56 };
+
+  return (
+    <Text
+      component="time"
+      dateTime={now.toISOString()}
+      fz={fontSize}
+      fw={700}
+      ff="var(--mantine-font-family-monospace)"
+      lh={1}
+      lts="-0.04em"
+      aria-label={t("worldClock.accessibleTime", {
+        city: entry.label,
+        time: formattedTime,
+        date: accessibleDate,
+        timeZone: entry.timeZone,
+      })}
+    >
+      {formattedTime}
+    </Text>
+  );
+};
+
+const DayAndOffset = ({ entry, now, primaryOffset }: Pick<ClockEntryProps, "entry" | "now" | "primaryOffset">) => {
+  const locale = useCurrentIntlLocale();
+  const t = useScopedI18n("widget.clock");
+  if (entry.dayDifference === null || entry.utcOffset === null) return null;
+  const dayRelation = getDayRelation(entry.dayDifference, t);
+  const date = formatLocalizedDate(now, locale, {
+    weekday: "short",
+    month: "short",
+    day: "numeric",
+    timeZone: entry.timeZone,
+  });
+
+  return (
+    <Group gap="xs" wrap="wrap">
+      <Badge color="gray" variant="light" size="sm" tt="none">
+        {date} · {dayRelation}
+      </Badge>
+      <Text size="xs" c="dimmed">
+        {formatRelativeOffset(entry.utcOffset - primaryOffset)} · {formatUtcOffset(entry.utcOffset)}
+      </Text>
+    </Group>
+  );
+};
+
+const InvalidTimeZone = ({ entry }: { entry: WorldClockTime }) => {
+  const t = useScopedI18n("widget.clock");
+  return (
+    <Paper component="li" withBorder radius="md" p="md">
+      <Group gap="xs" wrap="nowrap">
+        <IconAlertTriangle color="var(--mantine-color-yellow-6)" aria-hidden />
+        <Box>
+          <Text fw={600}>{entry.label}</Text>
+          <Text size="xs" c="dimmed">
+            {t("worldClock.unsupportedTimeZone", { timeZone: entry.timeZone })}
+          </Text>
+        </Box>
+      </Group>
+    </Paper>
+  );
+};
+
+const EmptyCities = () => {
+  const t = useScopedI18n("widget.clock");
+  return (
+    <Paper withBorder radius="md" p="xl">
+      <Text c="dimmed" ta="center">
+        {t("worldClock.noSecondaryCities")}
+      </Text>
+    </Paper>
+  );
+};
+
+type ScopedClockTranslator = ReturnType<typeof useScopedI18n<"widget.clock">>;
+
+const getDayRelation = (difference: number, t: ScopedClockTranslator) => {
+  if (difference < 0) return t("worldClock.yesterday");
+  if (difference > 0) return t("worldClock.tomorrow");
+  return t("worldClock.today");
+};
+
+const getPrimaryLabel = (options: ModeProps["options"], t: ScopedClockTranslator) => {
+  if (options.customTitleToggle) return options.customTitle || t("worldClock.primary");
+  if (options.useCustomTimezone) return humanizeTimeZone(options.timezone);
+  return t("worldClock.local");
+};
+
+const getPhaseColor = (phase: TimeOfDayPhase) => {
+  if (phase === "night") return "indigo";
+  if (phase === "dawn") return "orange";
+  if (phase === "day") return "cyan";
+  return "grape";
+};

packages/widgets/src/clock/component.tsx

@@ -1,51 +1,62 @@
 "use client";
 
-import { useEffect, useMemo, useRef, useState } from "react";
-import { Box, Group, Loader, Stack, Text, Title } from "@mantine/core";
+import { Box, Center, Stack, Text, Title } from "@mantine/core";
 import dayjs from "dayjs";
 import advancedFormat from "dayjs/plugin/advancedFormat";
-import timezones from "dayjs/plugin/timezone";
-import utc from "dayjs/plugin/utc";
 
-import { clientApi } from "@homarr/api/client";
-import { metricToImperial } from "@homarr/common";
-import { useI18n, useScopedI18n } from "@homarr/translation/client";
-
-import { isInitialWidgetQueryPending } from "../common/query-state";
-import { WidgetQueryErrorIndicator } from "../common/query-state-indicator";
 import type { WidgetComponentProps } from "../definition";
-import { AnimatedWeatherIcon } from "../weather/animated-icon";
-import { WeatherDescription } from "../weather/icon";
+import { AdvancedClockView } from "./advanced-view";
+import { clockTimeFormatShowsSeconds, resolveClockTimeFormat } from "./format";
+import { useCurrentTime } from "./use-current-time";
+import { ClockWeatherSummary } from "./weather-summary";
+import { getResolvedLocalTimeZone, isTimeZoneSupported } from "./world-clock";
 
 dayjs.extend(advancedFormat);
-dayjs.extend(utc);
-dayjs.extend(timezones);
 
 export default function ClockWidget({ options, width, height, displayMode }: WidgetComponentProps<"clock">) {
   const isAdvanced = displayMode === "advanced";
-  const secondsFormat = options.showSeconds || isAdvanced ? ":ss" : "";
-  const timeFormat = options.is24HourFormat ? `HH:mm${secondsFormat}` : `hh:mm${secondsFormat} A`;
-  const dateFormat = options.dateFormat;
-  const customTimeFormat = options.customTimeFormat;
-  const customDateFormat = options.customDateFormat;
-  const timezone = options.useCustomTimezone ? options.timezone : Intl.DateTimeFormat().resolvedOptions().timeZone;
-  const time = useCurrentTime({ showSeconds: options.showSeconds || isAdvanced });
-  const zonedTime = time === null ? null : dayjs(time).tz(timezone);
+  const showSeconds = clockTimeFormatShowsSeconds(options.customTimeFormat);
+  const time = useCurrentTime({ showSeconds });
+  const requestedTimeZone = options.useCustomTimezone ? options.timezone : getResolvedLocalTimeZone();
+  const primaryTimeZoneInvalid = !isTimeZoneSupported(requestedTimeZone);
+  const primaryTimeZone = primaryTimeZoneInvalid ? "UTC" : requestedTimeZone;
+  const zonedTime = time === null ? null : dayjs(time).tz(primaryTimeZone);
 
+  if (isAdvanced) {
+    if (time && zonedTime) {
+      return (
+        <AdvancedClockView
+          now={time}
+          options={options}
+          primaryTime={zonedTime}
+          primaryTimeZone={primaryTimeZone}
+          primaryTimeZoneInvalid={primaryTimeZoneInvalid}
+        />
+      );
+    }
+    return <Center h="100%">--:--</Center>;
+  }
+
+  const resolvedTimeFormat = resolveClockTimeFormat(options.customTimeFormat, options.is24HourFormat);
   const minimumAxis = Math.min(width, height * 1.5);
-  const sizing = minimumAxis < 128 ? "xs" : minimumAxis < 196 ? "sm" : "md";
+  let sizing: "xs" | "sm" | "md" = "md";
+  if (minimumAxis < 128) sizing = "xs";
+  else if (minimumAxis < 196) sizing = "sm";
   const showWeatherCorner = options.showWeather && sizing !== "xs";
 
   return (
     <Box className="clock-widget-container" h="100%" pos="relative">
       {showWeatherCorner && (
-        <ClockWeatherCorner
-          latitude={options.weatherLocation.latitude}
-          longitude={options.weatherLocation.longitude}
-          locationName={options.weatherLocation.name}
-          isFahrenheit={options.isWeatherFormatFahrenheit}
-          showDetails={isAdvanced}
-        />
+        <Box pos="absolute" top={4} left={4}>
+          <ClockWeatherSummary
+            latitude={options.weatherLocation.latitude}
+            longitude={options.weatherLocation.longitude}
+            locationName={options.weatherLocation.name}
+            isFahrenheit={options.isWeatherFormatFahrenheit}
+            animateIcon={options.animateWeatherIcon}
+            detailed={false}
+          />
+        </Box>
       )}
       <Stack className="clock-text-stack" h="100%" align="center" justify="center" gap={sizing}>
         {options.customTitleToggle && (
@@ -53,19 +64,14 @@ export default function ClockWidget({ options, width, height, displayMode }: Wid
             {options.customTitle}
           </Text>
         )}
-        <Title className="clock-time-text" fw={700} order={sizing === "md" ? 2 : sizing === "sm" ? 4 : 6} lh="1">
+        <Title className="clock-time-text" fw={700} order={getTitleOrder(sizing)} lh="1">
           <time dateTime={zonedTime?.toISOString()}>
-            {zonedTime === null ? "--:--" : zonedTime.format(options.customTimeFormat ? customTimeFormat : timeFormat)}
+            {zonedTime === null ? "--:--" : zonedTime.format(resolvedTimeFormat)}
           </time>
         </Title>
-        {(isAdvanced || options.showDate) && (
+        {options.showDate && (
           <Text className="clock-date-text" size={sizing} lineClamp={1}>
-            {zonedTime?.format(options.customDateFormat ? customDateFormat : dateFormat)}
-          </Text>
-        )}
-        {isAdvanced && (
-          <Text size="xs" c="dimmed" lineClamp={1}>
-            {zonedTime === null ? null : `${timezone} · UTC${zonedTime.format("Z")}`}
+            {zonedTime?.format(options.dateFormat)}
           </Text>
         )}
       </Stack>
@@ -73,117 +79,8 @@ export default function ClockWidget({ options, width, height, displayMode }: Wid
   );
 }
 
-interface ClockWeatherCornerProps {
-  latitude: number;
-  longitude: number;
-  locationName: string;
-  isFahrenheit: boolean;
-  showDetails: boolean;
-}
-
-const ClockWeatherCorner = ({
-  latitude,
-  longitude,
-  locationName,
-  isFahrenheit,
-  showDetails,
-}: ClockWeatherCornerProps) => {
-  const t = useI18n();
-  const tCommon = useScopedI18n("common");
-  const weatherQuery = clientApi.widget.weather.atLocation.useQuery({ latitude, longitude });
-  const weather = weatherQuery.data;
-
-  if (!weather) {
-    return (
-      <Box pos="absolute" top={4} left={4}>
-        {isInitialWidgetQueryPending(weatherQuery) ? (
-          <Loader size="xs" aria-label={tCommon("action.loading")} />
-        ) : (
-          <WidgetQueryErrorIndicator error={weatherQuery.error} label={t("widget.weather.name")} />
-        )}
-      </Box>
-    );
-  }
-
-  const temp = isFahrenheit ? weather.current.temperature * (9 / 5) + 32 : weather.current.temperature;
-  const unit = isFahrenheit ? "°F" : "°C";
-  const today = weather.daily[0];
-  const formatTemperature = (value: number | undefined) => {
-    if (value === undefined) return "—";
-    const preferred = isFahrenheit ? value * (9 / 5) + 32 : value;
-    return `${Math.round(preferred)}${unit}`;
-  };
-
-  return (
-    <Stack
-      className="clock-weather-corner"
-      pos="absolute"
-      top={4}
-      left={4}
-      gap={showDetails ? 4 : 0}
-      align="flex-start"
-    >
-      <Group gap={4} wrap="nowrap">
-        <AnimatedWeatherIcon code={weather.current.weathercode} size={22} />
-        <Text className="clock-weather-corner-temp" size="xs" c="dimmed">
-          {Math.round(temp)}
-          {unit}
-        </Text>
-        {showDetails && <WeatherDescription weatherOnly weatherCode={weather.current.weathercode} />}
-      </Group>
-      {showDetails && (
-        <Stack gap={1}>
-          <Text size="xs" fw={600}>
-            {locationName}
-          </Text>
-          <Text size="xs" c="dimmed">
-            {formatTemperature(today?.maxTemp)} / {formatTemperature(today?.minTemp)} · {today?.humidity ?? "—"}%
-          </Text>
-          <Text size="xs" c="dimmed">
-            {Math.round(isFahrenheit ? metricToImperial(weather.current.windspeed) : weather.current.windspeed)}{" "}
-            {isFahrenheit ? tCommon("unit.speed.milesPerHour") : tCommon("unit.speed.kilometersPerHour")}
-          </Text>
-          <Text size="xs" c="dimmed">
-            {t("widget.weather.dailyForecast.sunrise")}: {formatClockWeatherTime(today?.sunrise)} ·{" "}
-            {t("widget.weather.dailyForecast.sunset")}: {formatClockWeatherTime(today?.sunset)}
-          </Text>
-        </Stack>
-      )}
-      <WidgetQueryErrorIndicator error={weatherQuery.error} label={t("widget.weather.name")} />
-    </Stack>
-  );
-};
-
-const formatClockWeatherTime = (value: string | undefined) => value?.split("T")[1] ?? "—";
-
-interface UseCurrentTimeProps {
-  showSeconds: boolean;
-}
-
-const useCurrentTime = ({ showSeconds }: UseCurrentTimeProps) => {
-  const [time, setTime] = useState<Date | null>(null);
-  const timeoutRef = useRef<NodeJS.Timeout>(null);
-  const intervalRef = useRef<NodeJS.Timeout>(null);
-  const intervalMultiplier = useMemo(() => (showSeconds ? 1 : 60), [showSeconds]);
-
-  useEffect(() => {
-    setTime(new Date());
-    timeoutRef.current = setTimeout(
-      () => {
-        setTime(new Date());
-
-        intervalRef.current = setInterval(() => {
-          setTime(new Date());
-        }, intervalMultiplier * 1000);
-      },
-      intervalMultiplier * 1000 - (1000 * (showSeconds ? 0 : dayjs().second()) + dayjs().millisecond()),
-    );
-
-    return () => {
-      if (timeoutRef.current) clearTimeout(timeoutRef.current);
-      if (intervalRef.current) clearInterval(intervalRef.current);
-    };
-  }, [intervalMultiplier, showSeconds]);
-
-  return time;
+const getTitleOrder = (sizing: "xs" | "sm" | "md") => {
+  if (sizing === "md") return 2;
+  if (sizing === "sm") return 4;
+  return 6;
 };

packages/widgets/src/clock/format.ts

@@ -0,0 +1,19 @@
+export const automaticTimeFormat = "automatic";
+
+export const resolveClockTimeFormat = (format: string, legacyIs24HourFormat: boolean) => {
+  if (format && format !== automaticTimeFormat) return format;
+  if (legacyIs24HourFormat) return "HH:mm";
+  return "hh:mm A";
+};
+
+export const clockTimeFormatUses12Hours = (format: string, legacyIs24HourFormat: boolean) => {
+  if (!format || format === automaticTimeFormat) return !legacyIs24HourFormat;
+  const formatWithoutLiterals = format.replace(/\[[^\]]*\]/g, "");
+  return /h{1,2}/.test(formatWithoutLiterals);
+};
+
+export const clockTimeFormatShowsSeconds = (format: string) => {
+  if (!format || format === automaticTimeFormat) return false;
+  const formatWithoutLiterals = format.replace(/\[[^\]]*\]/g, "");
+  return /s{1,2}/.test(formatWithoutLiterals);
+};

packages/widgets/src/clock/index.ts

@@ -3,9 +3,18 @@ import dayjs from "dayjs";
 
 import { createWidgetDefinition, widgetQueryInputMatches } from "../definition";
 import { optionsBuilder } from "../options";
+import {
+  defaultWorldClockCities,
+  getTimeZoneOptions,
+  maximumWorldClockCities,
+  worldClockCityPresets,
+} from "./world-clock";
+
+const timeZoneOptions = getTimeZoneOptions();
 
 export const { definition, componentLoader } = createWidgetDefinition("clock", {
   icon: IconClock,
+  supportsAdvancedFocus: true,
   queryKey: [["widget", "weather", "atLocation"]],
   queryMatcher: ({ input }, scope) => {
     const location = scope.options.weatherLocation;
@@ -37,12 +46,9 @@ export const { definition, componentLoader } = createWidgetDefinition("clock", {
           defaultValue: true,
           withDescription: true,
         }),
-        showSeconds: factory.switch({
-          defaultValue: false,
-        }),
         useCustomTimezone: factory.switch({ defaultValue: false }),
         timezone: factory.select({
-          options: Intl.supportedValuesOf("timeZone").map((value) => value),
+          options: timeZoneOptions,
           defaultValue: "Europe/London",
           searchable: true,
           withDescription: true,
@@ -52,24 +58,29 @@ export const { definition, componentLoader } = createWidgetDefinition("clock", {
         }),
         dateFormat: factory.select({
           options: [
-            { value: "dddd, MMMM D", label: dayjs().format("dddd, MMMM D") },
-            { value: "dddd, D MMMM", label: dayjs().format("dddd, D MMMM") },
-            { value: "MMM D", label: dayjs().format("MMM D") },
-            { value: "D MMM", label: dayjs().format("D MMM") },
-            { value: "DD/MM/YYYY", label: dayjs().format("DD/MM/YYYY") },
-            { value: "MM/DD/YYYY", label: dayjs().format("MM/DD/YYYY") },
-            { value: "DD/MM", label: dayjs().format("DD/MM") },
-            { value: "MM/DD", label: dayjs().format("MM/DD") },
+            { value: "YYYY-MM-DD", label: `${dayjs().format("YYYY-MM-DD")} · YYYY-MM-DD` },
+            { value: "DD/MM/YYYY", label: `${dayjs().format("DD/MM/YYYY")} · DD/MM/YYYY` },
+            { value: "MM/DD/YYYY", label: `${dayjs().format("MM/DD/YYYY")} · MM/DD/YYYY` },
+            { value: "dddd, MMMM D", label: `${dayjs().format("dddd, MMMM D")} · dddd, MMMM D` },
+            { value: "dddd, D MMMM", label: `${dayjs().format("dddd, D MMMM")} · dddd, D MMMM` },
+            { value: "MMM D, YYYY", label: `${dayjs().format("MMM D, YYYY")} · MMM D, YYYY` },
+            { value: "D MMM YYYY", label: `${dayjs().format("D MMM YYYY")} · D MMM YYYY` },
+            { value: "MMM D", label: `${dayjs().format("MMM D")} · MMM D` },
+            { value: "D MMM", label: `${dayjs().format("D MMM")} · D MMM` },
+            { value: "DD/MM", label: `${dayjs().format("DD/MM")} · DD/MM` },
+            { value: "MM/DD", label: `${dayjs().format("MM/DD")} · MM/DD` },
           ],
           defaultValue: "dddd, MMMM D",
           withDescription: true,
         }),
-        customTimeFormat: factory.text({
-          defaultValue: "",
-          withDescription: true,
-        }),
-        customDateFormat: factory.text({
-          defaultValue: "",
+        customTimeFormat: factory.select({
+          options: [
+            { value: "HH:mm", label: `${dayjs().format("HH:mm")} · HH:mm` },
+            { value: "HH:mm:ss", label: `${dayjs().format("HH:mm:ss")} · HH:mm:ss` },
+            { value: "h:mm A", label: `${dayjs().format("h:mm A")} · h:mm A` },
+            { value: "h:mm:ss A", label: `${dayjs().format("h:mm:ss A")} · h:mm:ss A` },
+          ],
+          defaultValue: "HH:mm",
           withDescription: true,
         }),
         showWeather: factory.switch({
@@ -86,8 +97,22 @@ export const { definition, componentLoader } = createWidgetDefinition("clock", {
         isWeatherFormatFahrenheit: factory.switch({
           defaultValue: false,
         }),
+        animateWeatherIcon: factory.switch({
+          defaultValue: false,
+          withDescription: true,
+        }),
+        worldClockCities: factory.timezoneList({
+          defaultValue: defaultWorldClockCities.map((city) => ({ ...city })),
+          maxValues: maximumWorldClockCities,
+          presets: worldClockCityPresets,
+          timeZoneOptions,
+          withDescription: true,
+        }),
       }),
       {
+        is24HourFormat: {
+          shouldHide: () => true,
+        },
         customTitle: {
           shouldHide: (options) => !options.customTitleToggle,
         },
@@ -103,6 +128,9 @@ export const { definition, componentLoader } = createWidgetDefinition("clock", {
         isWeatherFormatFahrenheit: {
           shouldHide: (options) => !options.showWeather,
         },
+        animateWeatherIcon: {
+          shouldHide: (options) => !options.showWeather,
+        },
       },
     );
   },

packages/widgets/src/clock/time-of-day-bar.tsx

@@ -0,0 +1,108 @@
+import { Badge, Box, Group, Progress, Stack, Text } from "@mantine/core";
+
+import { useScopedI18n } from "@homarr/translation/client";
+
+import type { TimeOfDayPhase } from "./world-clock";
+
+interface TimeOfDayBarProps {
+  minuteOfDay: number;
+  phase: TimeOfDayPhase;
+  showLegend?: boolean;
+  showTicks?: boolean;
+  label: string;
+}
+
+const phaseSections = [
+  { key: "nightStart", value: 20.833, color: "indigo.8" },
+  { key: "dawn", value: 12.5, color: "orange.6" },
+  { key: "day", value: 41.667, color: "cyan.6" },
+  { key: "dusk", value: 12.5, color: "grape.6" },
+  { key: "nightEnd", value: 12.5, color: "indigo.8" },
+] as const;
+
+const phaseLegend = [
+  { key: "night", color: "indigo.8" },
+  { key: "dawn", color: "orange.6" },
+  { key: "day", color: "cyan.6" },
+  { key: "dusk", color: "grape.6" },
+] as const;
+
+const timeTicks = ["midnight", "morning", "noon", "evening", "end"] as const;
+
+export const TimeOfDayBar = ({
+  minuteOfDay,
+  phase,
+  showLegend = false,
+  showTicks = false,
+  label,
+}: TimeOfDayBarProps) => {
+  const t = useScopedI18n("widget.clock");
+  const progress = Math.max(0, Math.min(100, (minuteOfDay / 1440) * 100));
+  const remainingMinutes = Math.max(0, 1440 - Math.floor(minuteOfDay));
+  const remainingHours = Math.floor(remainingMinutes / 60);
+  const remainder = remainingMinutes % 60;
+
+  return (
+    <Stack component="figure" gap={6} m={0} aria-label={label}>
+      <Group justify="space-between" align="center" gap="xs" wrap="nowrap">
+        <Badge color={getPhaseColor(phase)} variant="dot" size="sm">
+          {t(`worldClock.phase.${phase}`)}
+        </Badge>
+        <Text size="xs" c="dimmed" ta="right">
+          {t("worldClock.dayProgress", {
+            percent: Math.round(progress),
+            hours: remainingHours,
+            minutes: remainder.toString().padStart(2, "0"),
+          })}
+        </Text>
+      </Group>
+      <Box pos="relative">
+        <Progress.Root size="md" radius="xl" aria-hidden>
+          {phaseSections.map((section) => (
+            <Progress.Section key={section.key} value={section.value} color={section.color} withAria={false} />
+          ))}
+        </Progress.Root>
+        <Box
+          pos="absolute"
+          top="50%"
+          left={`${progress}%`}
+          w={4}
+          h={24}
+          bg="var(--mantine-color-text)"
+          style={{ borderRadius: "var(--mantine-radius-xl)", transform: "translate(-50%, -50%)" }}
+        />
+      </Box>
+      {showTicks && (
+        <Group justify="space-between" wrap="nowrap">
+          {timeTicks.map((tick) => (
+            <Text key={tick} size="xs" c="dimmed" aria-hidden>
+              {t(`worldClock.tick.${tick}`)}
+            </Text>
+          ))}
+        </Group>
+      )}
+      {showLegend && (
+        <Group gap="md" mt={4} align="center" wrap="wrap">
+          <Text size="xs" fw={600}>
+            {t("worldClock.phaseLegend")}
+          </Text>
+          {phaseLegend.map((item) => (
+            <Group key={item.key} gap={6} wrap="nowrap">
+              <Box w={9} h={9} bg={item.color} style={{ borderRadius: "var(--mantine-radius-xl)" }} />
+              <Text size="xs" c="dimmed">
+                {t(`worldClock.phase.${item.key}`)} · {t(`worldClock.phaseRange.${item.key}`)}
+              </Text>
+            </Group>
+          ))}
+        </Group>
+      )}
+    </Stack>
+  );
+};
+
+const getPhaseColor = (phase: TimeOfDayPhase) => {
+  if (phase === "night") return "indigo";
+  if (phase === "dawn") return "orange";
+  if (phase === "day") return "cyan";
+  return "grape";
+};

packages/widgets/src/clock/use-current-time.ts

@@ -0,0 +1,27 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import dayjs from "dayjs";
+
+export const useCurrentTime = ({ showSeconds }: { showSeconds: boolean }) => {
+  const [time, setTime] = useState<Date | null>(null);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout>>(null);
+  const intervalRef = useRef<ReturnType<typeof setInterval>>(null);
+  const intervalMultiplier = useMemo(() => (showSeconds ? 1 : 60), [showSeconds]);
+
+  useEffect(() => {
+    setTime(new Date());
+    timeoutRef.current = setTimeout(
+      () => {
+        setTime(new Date());
+        intervalRef.current = setInterval(() => setTime(new Date()), intervalMultiplier * 1000);
+      },
+      intervalMultiplier * 1000 - (1000 * (showSeconds ? 0 : dayjs().second()) + dayjs().millisecond()),
+    );
+
+    return () => {
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+      if (intervalRef.current) clearInterval(intervalRef.current);
+    };
+  }, [intervalMultiplier, showSeconds]);
+
+  return time;
+};

packages/widgets/src/clock/weather-summary.tsx

@@ -0,0 +1,78 @@
+import { Box, Group, Loader, Stack, Text } from "@mantine/core";
+
+import { clientApi } from "@homarr/api/client";
+import { useI18n, useScopedI18n } from "@homarr/translation/client";
+
+import { isInitialWidgetQueryPending } from "../common/query-state";
+import { WidgetQueryErrorIndicator } from "../common/query-state-indicator";
+import { AnimatedWeatherIcon } from "../weather/animated-icon";
+import { WeatherDescription } from "../weather/icon";
+
+interface ClockWeatherSummaryProps {
+  latitude: number;
+  longitude: number;
+  locationName: string;
+  isFahrenheit: boolean;
+  animateIcon: boolean;
+  detailed: boolean;
+}
+
+export const ClockWeatherSummary = ({
+  latitude,
+  longitude,
+  locationName,
+  isFahrenheit,
+  animateIcon,
+  detailed,
+}: ClockWeatherSummaryProps) => {
+  const t = useI18n();
+  const tCommon = useScopedI18n("common");
+  const weatherQuery = clientApi.widget.weather.atLocation.useQuery({ latitude, longitude });
+  const weather = weatherQuery.data;
+
+  if (!weather) {
+    return isInitialWidgetQueryPending(weatherQuery) ? (
+      <Loader size="xs" aria-label={tCommon("action.loading")} />
+    ) : (
+      <WidgetQueryErrorIndicator error={weatherQuery.error} label={t("widget.weather.name")} />
+    );
+  }
+
+  const temperature = isFahrenheit ? weather.current.temperature * (9 / 5) + 32 : weather.current.temperature;
+  const unit = isFahrenheit ? "°F" : "°C";
+  const today = weather.daily[0];
+  const formatTemperature = (value: number | null | undefined) => {
+    if (value === undefined || value === null) return "—";
+    const preferred = isFahrenheit ? value * (9 / 5) + 32 : value;
+    return `${Math.round(preferred)}${unit}`;
+  };
+
+  return (
+    <Stack gap={detailed ? 3 : 0} align="flex-start">
+      <Group gap={5} wrap="nowrap">
+        <AnimatedWeatherIcon
+          animated={animateIcon}
+          code={weather.current.weatherCode}
+          isDay={weather.current.isDay}
+          size={detailed ? 28 : 22}
+        />
+        <Text size={detailed ? "sm" : "xs"} fw={detailed ? 600 : undefined} c={detailed ? undefined : "dimmed"}>
+          {Math.round(temperature)}
+          {unit}
+        </Text>
+        {detailed && <WeatherDescription weatherOnly weatherCode={weather.current.weatherCode} />}
+      </Group>
+      {detailed && (
+        <Box>
+          <Text size="xs" fw={600} lineClamp={1}>
+            {locationName}
+          </Text>
+          <Text size="xs" c="dimmed">
+            {formatTemperature(today?.maxTemperature)} / {formatTemperature(today?.minTemperature)}
+          </Text>
+        </Box>
+      )}
+      <WidgetQueryErrorIndicator error={weatherQuery.error} label={t("widget.weather.name")} />
+    </Stack>
+  );
+};

packages/widgets/src/clock/world-clock.spec.ts

@@ -0,0 +1,63 @@
+import dayjs from "dayjs";
+import { describe, expect, test } from "vitest";
+
+import {
+  createWorldClockTime,
+  formatRelativeOffset,
+  formatUtcOffset,
+  getTimeOfDayPhase,
+  getTimeZoneOptions,
+} from "./world-clock";
+
+describe("world clock helpers", () => {
+  test("adds UTC to the available timezone options", () => {
+    expect(getTimeZoneOptions()).toContainEqual({ value: "UTC", label: "UTC (UTC)" });
+  });
+
+  test("classifies the fixed time-of-day phases at their boundaries", () => {
+    expect([0, 4, 5, 7, 8, 17, 18, 20, 21, 23].map(getTimeOfDayPhase)).toEqual([
+      "night",
+      "night",
+      "dawn",
+      "dawn",
+      "day",
+      "day",
+      "dusk",
+      "dusk",
+      "night",
+      "night",
+    ]);
+  });
+
+  test("formats whole-hour and fractional offsets", () => {
+    expect(formatUtcOffset(345)).toBe("UTC+05:45");
+    expect(formatRelativeOffset(-210)).toBe("−3h 30m");
+    expect(formatRelativeOffset(0)).toBe("±0h");
+  });
+
+  test("compares civil dates across the date line from one instant", () => {
+    const now = new Date("2026-01-01T02:30:00.000Z");
+    const primaryTime = dayjs(now).tz("America/New_York");
+    const tokyo = createWorldClockTime({
+      city: { id: "tokyo", label: "Tokyo", timeZone: "Asia/Tokyo" },
+      now,
+      primaryTime,
+    });
+
+    expect(primaryTime.format("YYYY-MM-DD")).toBe("2025-12-31");
+    expect(tokyo.zonedTime?.format("YYYY-MM-DD")).toBe("2026-01-01");
+    expect(tokyo.dayDifference).toBe(1);
+  });
+
+  test("isolates unsupported timezones", () => {
+    const now = new Date("2026-01-01T00:00:00.000Z");
+    const result = createWorldClockTime({
+      city: { id: "invalid", label: "Invalid", timeZone: "Invalid/Timezone" },
+      now,
+      primaryTime: dayjs(now).tz("UTC"),
+    });
+
+    expect(result.zonedTime).toBeNull();
+    expect(result.utcOffset).toBeNull();
+  });
+});

packages/widgets/src/clock/world-clock.ts

@@ -0,0 +1,127 @@
+import dayjs from "dayjs";
+import type { Dayjs } from "dayjs";
+import timezone from "dayjs/plugin/timezone";
+import utc from "dayjs/plugin/utc";
+
+import type { OptionTimezone } from "../options";
+
+dayjs.extend(utc);
+dayjs.extend(timezone);
+
+export const maximumWorldClockCities = 6;
+
+export const worldClockCityPresets = [
+  { id: "new-york", label: "New York", timeZone: "America/New_York" },
+  { id: "london", label: "London", timeZone: "Europe/London" },
+  { id: "paris", label: "Paris", timeZone: "Europe/Paris" },
+  { id: "tokyo", label: "Tokyo", timeZone: "Asia/Tokyo" },
+  { id: "sydney", label: "Sydney", timeZone: "Australia/Sydney" },
+  { id: "utc", label: "UTC", timeZone: "UTC" },
+] as const satisfies readonly OptionTimezone[];
+
+export const defaultWorldClockCities = worldClockCityPresets.filter(({ id }) =>
+  ["new-york", "paris", "tokyo"].includes(id),
+);
+
+export const getTimeZoneOptions = () => {
+  const timeZones = Intl.supportedValuesOf("timeZone");
+  if (!timeZones.includes("UTC")) timeZones.push("UTC");
+
+  return timeZones.map((timeZone) => ({
+    value: timeZone,
+    label: `${humanizeTimeZone(timeZone)} (${timeZone})`,
+  }));
+};
+
+export const humanizeTimeZone = (timeZone: string) => {
+  if (timeZone === "UTC") return "UTC";
+  const segments = timeZone.split("/");
+  return (segments.at(-1) ?? timeZone).replaceAll("_", " ");
+};
+
+export const isTimeZoneSupported = (timeZone: string) => {
+  try {
+    new Intl.DateTimeFormat("en", { timeZone }).format(0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export type TimeOfDayPhase = "night" | "dawn" | "day" | "dusk";
+
+export interface WorldClockTime {
+  id: string;
+  label: string;
+  timeZone: string;
+  zonedTime: Dayjs | null;
+  phase: TimeOfDayPhase | null;
+  minuteOfDay: number | null;
+  utcOffset: number | null;
+  dayDifference: number | null;
+}
+
+export const getResolvedLocalTimeZone = () => {
+  const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  return timeZone && isTimeZoneSupported(timeZone) ? timeZone : "UTC";
+};
+
+export const createWorldClockTime = ({
+  city,
+  now,
+  primaryTime,
+}: {
+  city: OptionTimezone;
+  now: Date;
+  primaryTime: Dayjs;
+}): WorldClockTime => {
+  if (!isTimeZoneSupported(city.timeZone)) {
+    return {
+      ...city,
+      zonedTime: null,
+      phase: null,
+      minuteOfDay: null,
+      utcOffset: null,
+      dayDifference: null,
+    };
+  }
+
+  const zonedTime = dayjs(now).tz(city.timeZone);
+  return {
+    ...city,
+    zonedTime,
+    phase: getTimeOfDayPhase(zonedTime.hour()),
+    minuteOfDay: zonedTime.hour() * 60 + zonedTime.minute() + zonedTime.second() / 60,
+    utcOffset: zonedTime.utcOffset(),
+    dayDifference: getCivilDayNumber(zonedTime) - getCivilDayNumber(primaryTime),
+  };
+};
+
+export const getTimeOfDayPhase = (hour: number): TimeOfDayPhase => {
+  if (hour < 5 || hour >= 21) return "night";
+  if (hour < 8) return "dawn";
+  if (hour < 18) return "day";
+  return "dusk";
+};
+
+export const formatUtcOffset = (minutes: number) => {
+  if (minutes === 0) return "UTC±00:00";
+  const sign = minutes < 0 ? "−" : "+";
+  const absoluteMinutes = Math.abs(minutes);
+  const hours = Math.floor(absoluteMinutes / 60)
+    .toString()
+    .padStart(2, "0");
+  const remainingMinutes = (absoluteMinutes % 60).toString().padStart(2, "0");
+  return `UTC${sign}${hours}:${remainingMinutes}`;
+};
+
+export const formatRelativeOffset = (minutes: number) => {
+  if (minutes === 0) return "±0h";
+  const sign = minutes < 0 ? "−" : "+";
+  const absoluteMinutes = Math.abs(minutes);
+  const hours = Math.floor(absoluteMinutes / 60);
+  const remainingMinutes = absoluteMinutes % 60;
+  return remainingMinutes === 0 ? `${sign}${hours}h` : `${sign}${hours}h ${remainingMinutes}m`;
+};
+
+const getCivilDayNumber = (value: Dayjs) => Date.UTC(value.year(), value.month(), value.date()) / 86_400_000;

packages/widgets/src/common/browser-alert.spec.ts

@@ -0,0 +1,38 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { addRememberedBrowserAlert, requestBrowserNotificationPermission } from "./browser-alert";
+
+const originalNotification = window.Notification;
+
+afterEach(() => {
+  if (originalNotification === undefined) {
+    Reflect.deleteProperty(window, "Notification");
+    return;
+  }
+  Object.defineProperty(window, "Notification", { configurable: true, value: originalNotification });
+});
+
+describe("browser alert occurrence history", () => {
+  it("moves a repeated occurrence to the end without duplicating it", () => {
+    expect(addRememberedBrowserAlert(["first", "second"], "first")).toEqual(["second", "first"]);
+  });
+
+  it("bounds remembered occurrences", () => {
+    const values = Array.from({ length: 110 }, (_, index) => String(index));
+    const result = addRememberedBrowserAlert(values, "next");
+    expect(result).toHaveLength(100);
+    expect(result.at(-1)).toBe("next");
+  });
+
+  it("keeps the current permission when the browser rejects a permission request", async () => {
+    Object.defineProperty(window, "Notification", {
+      configurable: true,
+      value: {
+        permission: "default",
+        requestPermission: vi.fn().mockRejectedValue(new Error("blocked")),
+      },
+    });
+
+    await expect(requestBrowserNotificationPermission()).resolves.toBe("default");
+  });
+});

packages/widgets/src/common/browser-alert.ts

@@ -0,0 +1,87 @@
+export type BrowserNotificationPermission = NotificationPermission | "unsupported";
+
+export interface BrowserNotificationOptions {
+  title: string;
+  body?: string;
+  icon?: string;
+  tag?: string;
+}
+
+const maxRememberedOccurrences = 100;
+
+export const getBrowserNotificationPermission = (): BrowserNotificationPermission => {
+  if (typeof window === "undefined" || !("Notification" in window)) return "unsupported";
+  return window.Notification.permission;
+};
+
+export const requestBrowserNotificationPermission = async (): Promise<BrowserNotificationPermission> => {
+  if (typeof window === "undefined" || !("Notification" in window)) return "unsupported";
+  try {
+    return await window.Notification.requestPermission();
+  } catch {
+    return getBrowserNotificationPermission();
+  }
+};
+
+export const showBrowserNotification = ({ title, body, icon, tag }: BrowserNotificationOptions): boolean => {
+  if (typeof window === "undefined" || !("Notification" in window) || window.Notification.permission !== "granted") {
+    return false;
+  }
+
+  try {
+    const notification = new window.Notification(title, { body, icon, tag });
+    void notification;
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export const playBrowserAlertSound = (): boolean => {
+  if (typeof window === "undefined") return false;
+  const AudioContextConstructor =
+    window.AudioContext ?? (window as typeof window & { webkitAudioContext?: typeof AudioContext }).webkitAudioContext;
+  if (!AudioContextConstructor) return false;
+
+  try {
+    const context = new AudioContextConstructor();
+    const oscillator = context.createOscillator();
+    const gain = context.createGain();
+    const start = context.currentTime;
+    oscillator.type = "sine";
+    oscillator.frequency.setValueAtTime(880, start);
+    gain.gain.setValueAtTime(0.0001, start);
+    gain.gain.exponentialRampToValueAtTime(0.18, start + 0.01);
+    gain.gain.exponentialRampToValueAtTime(0.0001, start + 0.3);
+    oscillator.connect(gain);
+    gain.connect(context.destination);
+    oscillator.start(start);
+    oscillator.stop(start + 0.32);
+    oscillator.addEventListener("ended", () => void context.close(), { once: true });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export const addRememberedBrowserAlert = (occurrences: string[], occurrence: string): string[] => {
+  const withoutDuplicate = occurrences.filter((value) => value !== occurrence);
+  return [...withoutDuplicate, occurrence].slice(-maxRememberedOccurrences);
+};
+
+export const claimBrowserAlertOccurrence = (storageKey: string, occurrence: string): boolean => {
+  if (typeof window === "undefined") return false;
+
+  try {
+    const serialized = window.localStorage.getItem(storageKey);
+    const parsed: unknown = serialized === null ? [] : JSON.parse(serialized);
+    const occurrences = Array.isArray(parsed)
+      ? parsed.filter((value): value is string => typeof value === "string")
+      : [];
+    if (occurrences.includes(occurrence)) return false;
+    window.localStorage.setItem(storageKey, JSON.stringify(addRememberedBrowserAlert(occurrences, occurrence)));
+    return true;
+  } catch {
+    return false;
+  }
+};

packages/widgets/src/common/use-local-widget-state.spec.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+
+import { parseLocalWidgetState, serializeLocalWidgetState } from "./use-local-widget-state";
+
+const isCounterState = (value: unknown): value is { count: number } =>
+  typeof value === "object" && value !== null && "count" in value && typeof value.count === "number";
+
+describe("local widget state serialization", () => {
+  it("round trips validated state", () => {
+    const serialized = serializeLocalWidgetState(1, { count: 3 });
+    expect(parseLocalWidgetState(serialized, 1, isCounterState)).toEqual({ count: 3 });
+  });
+
+  it("rejects malformed and invalid state", () => {
+    expect(parseLocalWidgetState("not-json", 1, isCounterState)).toBeUndefined();
+    expect(parseLocalWidgetState('{"version":1,"value":{"count":"3"}}', 1, isCounterState)).toBeUndefined();
+  });
+
+  it("uses the supplied migration for old versions", () => {
+    const serialized = serializeLocalWidgetState(1, { oldCount: 4 });
+    expect(
+      parseLocalWidgetState(serialized, 2, isCounterState, (value) => {
+        if (typeof value !== "object" || value === null || !("oldCount" in value)) return undefined;
+        return { count: Number(value.oldCount) };
+      }),
+    ).toEqual({ count: 4 });
+  });
+});

packages/widgets/src/common/use-local-widget-state.ts

@@ -0,0 +1,146 @@
+"use client";
+
+import type { Dispatch, SetStateAction } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+interface StoredWidgetState {
+  version: number;
+  value: unknown;
+}
+
+interface UseLocalWidgetStateOptions<T> {
+  key: string | undefined;
+  version: number;
+  defaultValue: T | (() => T);
+  validate?: (value: unknown) => value is T;
+  migrate?: (value: unknown, storedVersion: number) => T | undefined;
+}
+
+const resolveDefaultValue = <T>(value: T | (() => T)): T =>
+  typeof value === "function" ? (value as () => T)() : value;
+
+export const serializeLocalWidgetState = <T>(version: number, value: T): string => JSON.stringify({ version, value });
+
+export const parseLocalWidgetState = <T>(
+  serialized: string,
+  version: number,
+  validate?: (value: unknown) => value is T,
+  migrate?: (value: unknown, storedVersion: number) => T | undefined,
+): T | undefined => {
+  try {
+    const parsed: unknown = JSON.parse(serialized);
+    if (typeof parsed !== "object" || parsed === null || !("version" in parsed) || !("value" in parsed)) {
+      return undefined;
+    }
+
+    const stored = parsed as StoredWidgetState;
+    if (typeof stored.version !== "number") return undefined;
+    if (stored.version !== version) {
+      const migrated = migrate?.(stored.value, stored.version);
+      if (migrated === undefined || (validate && !validate(migrated))) return undefined;
+      return migrated;
+    }
+    if (validate && !validate(stored.value)) return undefined;
+    return stored.value as T;
+  } catch {
+    return undefined;
+  }
+};
+
+export const useLocalWidgetState = <T>({
+  key,
+  version,
+  defaultValue,
+  validate,
+  migrate,
+}: UseLocalWidgetStateOptions<T>): [T, Dispatch<SetStateAction<T>>, () => void] => {
+  const defaultValueRef = useRef(defaultValue);
+  const validateRef = useRef(validate);
+  const migrateRef = useRef(migrate);
+  defaultValueRef.current = defaultValue;
+  validateRef.current = validate;
+  migrateRef.current = migrate;
+
+  const createDefaultValue = useCallback(() => resolveDefaultValue(defaultValueRef.current), []);
+  const [value, setValueState] = useState<T>(createDefaultValue);
+  const valueRef = useRef(value);
+
+  const setMemoryValue = useCallback((nextValue: T) => {
+    valueRef.current = nextValue;
+    setValueState(nextValue);
+  }, []);
+
+  const removeStoredValue = useCallback(() => {
+    if (!key) return;
+    try {
+      window.localStorage.removeItem(key);
+    } catch {
+      // Storage can be unavailable in private or restricted browser contexts.
+    }
+  }, [key]);
+
+  useEffect(() => {
+    if (!key) {
+      setMemoryValue(createDefaultValue());
+      return;
+    }
+
+    try {
+      const serialized = window.localStorage.getItem(key);
+      if (serialized === null) {
+        setMemoryValue(createDefaultValue());
+        return;
+      }
+      const parsed = parseLocalWidgetState(serialized, version, validateRef.current, migrateRef.current);
+      if (parsed === undefined) {
+        window.localStorage.removeItem(key);
+        setMemoryValue(createDefaultValue());
+        return;
+      }
+      setMemoryValue(parsed);
+    } catch {
+      setMemoryValue(createDefaultValue());
+    }
+  }, [createDefaultValue, key, setMemoryValue, version]);
+
+  useEffect(() => {
+    if (!key) return;
+
+    const handleStorage = (event: StorageEvent) => {
+      if (event.storageArea !== window.localStorage || event.key !== key) return;
+      if (event.newValue === null) {
+        setMemoryValue(createDefaultValue());
+        return;
+      }
+
+      const parsed = parseLocalWidgetState(event.newValue, version, validateRef.current, migrateRef.current);
+      if (parsed !== undefined) setMemoryValue(parsed);
+    };
+    window.addEventListener("storage", handleStorage);
+    return () => window.removeEventListener("storage", handleStorage);
+  }, [createDefaultValue, key, setMemoryValue, version]);
+
+  const setValue: Dispatch<SetStateAction<T>> = useCallback(
+    (nextValue) => {
+      const resolved =
+        typeof nextValue === "function" ? (nextValue as (previous: T) => T)(valueRef.current) : nextValue;
+      if (Object.is(resolved, valueRef.current)) return;
+      setMemoryValue(resolved);
+      if (key) {
+        try {
+          window.localStorage.setItem(key, serializeLocalWidgetState(version, resolved));
+        } catch {
+          // Keep the in-memory state usable when persistence is unavailable.
+        }
+      }
+    },
+    [key, setMemoryValue, version],
+  );
+
+  const resetValue = useCallback(() => {
+    removeStoredValue();
+    setMemoryValue(createDefaultValue());
+  }, [createDefaultValue, removeStoredValue, setMemoryValue]);
+
+  return [value, setValue, resetValue];
+};

packages/widgets/src/common/use-widget-now.spec.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+
+import { getNextWidgetTickDelay } from "./use-widget-now";
+
+describe("getNextWidgetTickDelay", () => {
+  it("aligns second and minute ticks", () => {
+    const now = new Date(2026, 7, 20, 12, 34, 45, 250);
+    expect(getNextWidgetTickDelay(now, "second")).toBe(750);
+    expect(getNextWidgetTickDelay(now, "minute")).toBe(14_750);
+  });
+
+  it("aligns day ticks to the next local midnight", () => {
+    const now = new Date(2026, 7, 20, 23, 59, 59, 500);
+    expect(getNextWidgetTickDelay(now, "day")).toBe(500);
+  });
+});

packages/widgets/src/common/use-widget-now.ts

@@ -0,0 +1,54 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export type WidgetClockPrecision = "second" | "minute" | "day";
+
+const minimumDelayMs = 10;
+
+export const getNextWidgetTickDelay = (now: Date, precision: WidgetClockPrecision): number => {
+  let next: number;
+  if (precision === "second") {
+    next = now.getTime() - now.getMilliseconds() + 1_000;
+  } else if (precision === "minute") {
+    next = now.getTime() - now.getSeconds() * 1_000 - now.getMilliseconds() + 60_000;
+  } else {
+    next = new Date(now.getFullYear(), now.getMonth(), now.getDate() + 1).getTime();
+  }
+
+  return Math.max(minimumDelayMs, next - now.getTime());
+};
+
+export const useWidgetNow = (precision: WidgetClockPrecision = "minute"): Date | null => {
+  const [now, setNow] = useState<Date | null>(null);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout>>(undefined);
+
+  const cancelTick = useCallback(() => {
+    if (timeoutRef.current === undefined) return;
+    clearTimeout(timeoutRef.current);
+    timeoutRef.current = undefined;
+  }, []);
+
+  const scheduleTick = useCallback(() => {
+    cancelTick();
+    const current = new Date();
+    setNow(current);
+    timeoutRef.current = setTimeout(scheduleTick, getNextWidgetTickDelay(current, precision));
+  }, [cancelTick, precision]);
+
+  useEffect(() => {
+    scheduleTick();
+
+    const handleVisibilityChange = () => {
+      if (document.visibilityState === "visible") scheduleTick();
+    };
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+
+    return () => {
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+      cancelTick();
+    };
+  }, [cancelTick, scheduleTick]);
+
+  return now;
+};

packages/widgets/src/countdown/component.module.css

@@ -0,0 +1,42 @@
+.root {
+  container-type: size;
+  overflow: hidden;
+}
+
+.duration {
+  font-variant-numeric: tabular-nums;
+  letter-spacing: -0.04em;
+}
+
+.compactDuration {
+  font-size: var(--mantine-font-size-xl);
+  white-space: nowrap;
+}
+
+.compactProgress {
+  width: 100%;
+  max-width: 14rem;
+}
+
+.eventCard {
+  min-width: 0;
+}
+
+@container (max-width: 10.625rem) {
+  .compactStatus,
+  .compactTarget {
+    display: none;
+  }
+}
+
+@container (max-width: 8.75rem) {
+  .compactDuration {
+    font-size: clamp(var(--mantine-font-size-sm), 15cqw, var(--mantine-font-size-md));
+  }
+}
+
+@container (max-height: 6.5625rem) {
+  .compactTarget {
+    display: none;
+  }
+}

packages/widgets/src/countdown/component.tsx

@@ -0,0 +1,361 @@
+"use client";
+
+import { useEffect, useMemo, useRef, useState } from "react";
+import {
+  Alert,
+  Badge,
+  Group,
+  Paper,
+  Progress,
+  ScrollArea,
+  SimpleGrid,
+  Stack,
+  Switch,
+  Text,
+  ThemeIcon,
+  Title,
+} from "@mantine/core";
+import { IconBell, IconBellOff, IconHourglass } from "@tabler/icons-react";
+
+import { useCurrentIntlLocale, useScopedI18n } from "@homarr/translation/client";
+
+import {
+  claimBrowserAlertOccurrence,
+  getBrowserNotificationPermission,
+  requestBrowserNotificationPermission,
+  showBrowserNotification,
+} from "../common/browser-alert";
+import { useLocalWidgetState } from "../common/use-local-widget-state";
+import { useWidgetNow } from "../common/use-widget-now";
+import type { WidgetComponentProps } from "../definition";
+import { formatCountdownDuration } from "./display";
+import styles from "./component.module.css";
+import { getCountdownEventState, getCountdownProgress, groupCountdownStates } from "./recurrence";
+import type { CountdownEventState } from "./recurrence";
+
+interface AlertPreferences {
+  notifications: boolean;
+}
+
+const defaultAlertPreferences: AlertPreferences = { notifications: false };
+
+const isAlertPreferences = (value: unknown): value is AlertPreferences => {
+  if (typeof value !== "object" || value === null) return false;
+  return "notifications" in value && typeof value.notifications === "boolean";
+};
+
+const migrateAlertPreferences = (value: unknown, storedVersion: number): AlertPreferences | undefined => {
+  if (storedVersion !== 1 || !isAlertPreferences(value)) return undefined;
+  return { notifications: value.notifications };
+};
+
+export default function CountdownWidget({
+  boardId,
+  displayMode,
+  isEditMode,
+  itemId,
+  options,
+  width,
+}: WidgetComponentProps<"countdown">) {
+  const now = useWidgetNow(options.showSeconds ? "second" : "minute");
+  const locale = useCurrentIntlLocale();
+  const t = useScopedI18n("widget.countdown");
+  const storagePrefix = boardId && itemId ? `homarr:countdown:${boardId}:${itemId}` : undefined;
+  const [preferences, setPreferences] = useLocalWidgetState<AlertPreferences>({
+    key: storagePrefix ? `${storagePrefix}:alert-preferences` : undefined,
+    version: 2,
+    defaultValue: defaultAlertPreferences,
+    validate: isAlertPreferences,
+    migrate: migrateAlertPreferences,
+  });
+  const [notificationPermission, setNotificationPermission] = useState(() => getBrowserNotificationPermission());
+  const previousNowRef = useRef<Date | null>(null);
+  const states = useMemo(() => {
+    if (!now) return [];
+    return options.events.map((event) => getCountdownEventState(event, now));
+  }, [now, options.events]);
+  const grouped = useMemo(() => groupCountdownStates(states), [states]);
+
+  useEffect(() => {
+    if (!now || !storagePrefix) return;
+    const previousNow = previousNowRef.current;
+    previousNowRef.current = now;
+    if (!previousNow || !preferences.notifications) return;
+
+    states.forEach((state) => {
+      const occurrence = state.previousOccurrence;
+      if (!occurrence || occurrence <= previousNow || occurrence > now) return;
+      const claimKey = `${storagePrefix}:alerted-occurrences`;
+      const occurrenceKey = `${state.event.id}:${occurrence.toISOString()}`;
+      if (!claimBrowserAlertOccurrence(claimKey, occurrenceKey)) return;
+      showBrowserNotification({
+        title: state.event.label,
+        body: t("alert.reached"),
+        tag: occurrenceKey,
+      });
+    });
+  }, [now, preferences.notifications, states, storagePrefix, t]);
+
+  if (!now) {
+    return (
+      <Stack h="100%" align="center" justify="center">
+        <Text c="dimmed">—</Text>
+      </Stack>
+    );
+  }
+
+  const hero = states[0];
+  if (!hero) {
+    return (
+      <Stack h="100%" align="center" justify="center" gap="xs" p="md">
+        <ThemeIcon variant="light" size="xl" radius="xl">
+          <IconHourglass />
+        </ThemeIcon>
+        <Text fw={600}>{t("empty.title")}</Text>
+        <Text size="sm" c="dimmed" ta="center">
+          {t("empty.description")}
+        </Text>
+      </Stack>
+    );
+  }
+
+  let heroStatus: string | null = null;
+  if (hero.invalid) heroStatus = t("invalid.value");
+  else if (hero.completed) heroStatus = t("completed");
+
+  if (displayMode !== "advanced") {
+    return (
+      <Stack className={styles.root} h="100%" justify="center" align="center" gap={6} p="sm">
+        <Group gap="xs" wrap="nowrap" maw="100%">
+          {heroStatus && (
+            <Badge className={styles.compactStatus} variant="outline" size="xs" flex="0 0 auto">
+              {heroStatus}
+            </Badge>
+          )}
+          <Text size="sm" fw={600} truncate>
+            {hero.event.label}
+          </Text>
+        </Group>
+        <CountdownValue state={hero} now={now} locale={locale} showSeconds={options.showSeconds} compact />
+        <Text className={styles.compactTarget} size="xs" c="dimmed" truncate maw="100%">
+          {formatOccurrence(hero, locale)}
+        </Text>
+        {options.showProgress && (
+          <ProgressBar className={styles.compactProgress} state={hero} now={now} label={t("progress")} />
+        )}
+      </Stack>
+    );
+  }
+
+  const setNotifications = async (enabled: boolean) => {
+    if (!enabled) {
+      setPreferences((current) => ({ ...current, notifications: false }));
+      return;
+    }
+    const permission = await requestBrowserNotificationPermission();
+    setNotificationPermission(permission);
+    if (permission === "granted") setPreferences((current) => ({ ...current, notifications: true }));
+  };
+  const eventColumns = width >= 700 ? 2 : 1;
+
+  return (
+    <Stack className={styles.root} h="100%" gap="md" p="md">
+      <Paper withBorder p="lg" radius="md">
+        <Stack gap="md">
+          <Group gap="xs" wrap="nowrap">
+            {heroStatus && <Badge variant="outline">{heroStatus}</Badge>}
+            <Text size="sm" c="dimmed" truncate>
+              {formatOccurrence(hero, locale)}
+            </Text>
+          </Group>
+          <Title order={2} lineClamp={1}>
+            {hero.event.label}
+          </Title>
+          <CountdownValue state={hero} now={now} locale={locale} showSeconds={options.showSeconds} />
+        </Stack>
+        {options.showProgress && <ProgressBar state={hero} now={now} label={t("progress")} />}
+      </Paper>
+
+      <AlertControls
+        disabled={isEditMode}
+        persistent={storagePrefix !== undefined}
+        preferences={preferences}
+        notificationPermission={notificationPermission}
+        onNotificationsChange={setNotifications}
+      />
+
+      <ScrollArea type="auto" style={{ flex: 1, minHeight: 0 }}>
+        <Stack gap="md" pb="xs">
+          <EventSection
+            title={t("upcoming")}
+            states={grouped.upcoming}
+            now={now}
+            locale={locale}
+            showSeconds={options.showSeconds}
+            showProgress={options.showProgress}
+            columns={eventColumns}
+          />
+          <EventSection
+            title={t("completedEvents")}
+            states={grouped.completed}
+            now={now}
+            locale={locale}
+            showSeconds={options.showSeconds}
+            showProgress={options.showProgress}
+            columns={eventColumns}
+          />
+          {grouped.invalid.length > 0 && (
+            <Alert color="yellow" title={t("invalid.title")}>
+              {t("invalid.description", { count: grouped.invalid.length })}
+            </Alert>
+          )}
+        </Stack>
+      </ScrollArea>
+    </Stack>
+  );
+}
+
+const CountdownValue = ({
+  state,
+  now,
+  locale,
+  showSeconds,
+  compact = false,
+}: {
+  state: CountdownEventState;
+  now: Date;
+  locale: string;
+  showSeconds: boolean;
+  compact?: boolean;
+}) => {
+  const t = useScopedI18n("widget.countdown");
+  let value = t("invalid.value");
+  if (state.completed) value = t("completed");
+  else if (state.nextOccurrence)
+    value = formatCountdownDuration(state, now, showSeconds, locale, compact ? "narrow" : "short");
+  return (
+    <Text
+      className={compact ? `${styles.duration} ${styles.compactDuration}` : styles.duration}
+      fz={compact ? undefined : 42}
+      fw={750}
+      lh={1.05}
+      ta={compact ? "center" : undefined}
+    >
+      {value}
+    </Text>
+  );
+};
+
+const ProgressBar = ({
+  className,
+  state,
+  now,
+  label,
+}: {
+  className?: string;
+  state: CountdownEventState;
+  now: Date;
+  label: string;
+}) => {
+  const progress = getCountdownProgress(state, now);
+  if (progress === null) return null;
+  return (
+    <Progress
+      className={className}
+      mt="xs"
+      value={progress}
+      aria-label={`${label}: ${Math.round(progress)}%`}
+      animated={false}
+    />
+  );
+};
+
+const EventSection = ({
+  title,
+  states,
+  now,
+  locale,
+  showSeconds,
+  showProgress,
+  columns,
+}: {
+  title: string;
+  states: CountdownEventState[];
+  now: Date;
+  locale: string;
+  showSeconds: boolean;
+  showProgress: boolean;
+  columns: number;
+}) => {
+  const t = useScopedI18n("widget.countdown");
+  if (states.length === 0) return null;
+  return (
+    <Stack gap="xs">
+      <Text fw={700}>{title}</Text>
+      <SimpleGrid cols={columns} spacing="xs">
+        {states.map((state) => (
+          <Paper className={styles.eventCard} key={state.event.id} withBorder p="sm">
+            <Stack gap={4} h="100%">
+              <Group justify="space-between" wrap="nowrap">
+                <Text fw={600} truncate>
+                  {state.event.label}
+                </Text>
+                {state.event.recurrence === "yearly" && <Badge variant="outline">{t("yearly")}</Badge>}
+              </Group>
+              <CountdownValue state={state} now={now} locale={locale} showSeconds={showSeconds} compact />
+              <Stack gap={4} mt="auto">
+                {showProgress && <ProgressBar state={state} now={now} label={title} />}
+                <Text size="xs" c="dimmed">
+                  {formatOccurrence(state, locale)}
+                </Text>
+              </Stack>
+            </Stack>
+          </Paper>
+        ))}
+      </SimpleGrid>
+    </Stack>
+  );
+};
+
+const AlertControls = ({
+  disabled,
+  persistent,
+  preferences,
+  notificationPermission,
+  onNotificationsChange,
+}: {
+  disabled: boolean;
+  persistent: boolean;
+  preferences: AlertPreferences;
+  notificationPermission: ReturnType<typeof getBrowserNotificationPermission>;
+  onNotificationsChange: (enabled: boolean) => Promise<void>;
+}) => {
+  const t = useScopedI18n("widget.countdown.alert");
+  if (!persistent) return null;
+  return (
+    <Paper withBorder p="sm" radius="md">
+      <Switch
+        checked={preferences.notifications && notificationPermission === "granted"}
+        disabled={disabled || notificationPermission === "unsupported" || notificationPermission === "denied"}
+        onChange={(event) => void onNotificationsChange(event.currentTarget.checked)}
+        label={t("notifications")}
+        thumbIcon={preferences.notifications ? <IconBell size={12} /> : <IconBellOff size={12} />}
+      />
+      {notificationPermission === "denied" && (
+        <Text size="xs" c="dimmed" mt="xs">
+          {t("permissionDenied")}
+        </Text>
+      )}
+    </Paper>
+  );
+};
+
+const formatOccurrence = (state: CountdownEventState, locale: string) => {
+  const occurrence = state.nextOccurrence ?? state.previousOccurrence;
+  if (!occurrence) return state.event.timeZone;
+  return new Intl.DateTimeFormat(locale, {
+    dateStyle: "medium",
+    timeStyle: "short",
+    timeZone: state.event.timeZone,
+  }).format(occurrence);
+};

packages/widgets/src/countdown/display.ts

@@ -0,0 +1,64 @@
+import type { CountdownEventState } from "./recurrence";
+
+const secondMs = 1_000;
+const minuteMs = 60 * secondMs;
+const hourMs = 60 * minuteMs;
+const dayMs = 24 * hourMs;
+
+export interface CountdownDurationPart {
+  unit: Intl.NumberFormatOptions["unit"];
+  value: number;
+}
+
+export const getCountdownDurationParts = (
+  state: CountdownEventState,
+  now: Date,
+  showSeconds: boolean,
+): CountdownDurationPart[] => {
+  const occurrence = state.nextOccurrence;
+  if (!occurrence) return [];
+  const remaining = Math.max(0, occurrence.getTime() - now.getTime());
+  const days = Math.floor(remaining / dayMs);
+  const hours = Math.floor((remaining % dayMs) / hourMs);
+  const minutes = Math.floor((remaining % hourMs) / minuteMs);
+  const seconds = Math.floor((remaining % minuteMs) / secondMs);
+
+  if (showSeconds) {
+    const parts: CountdownDurationPart[] = [];
+    if (days > 0) parts.push({ unit: "day", value: days });
+    if (days > 0 || hours > 0) parts.push({ unit: "hour", value: hours });
+    if (days > 0 || hours > 0 || minutes > 0) parts.push({ unit: "minute", value: minutes });
+    parts.push({ unit: "second", value: seconds });
+    return parts;
+  }
+
+  if (days > 0)
+    return compactParts([
+      { unit: "day", value: days },
+      { unit: "hour", value: hours },
+    ]);
+  if (hours > 0)
+    return compactParts([
+      { unit: "hour", value: hours },
+      { unit: "minute", value: minutes },
+    ]);
+  if (minutes > 0) return [{ unit: "minute", value: minutes }];
+  return [{ unit: "minute", value: 0 }];
+};
+
+const compactParts = (parts: CountdownDurationPart[]) => {
+  const nonZero = parts.filter(({ value }) => value > 0);
+  return nonZero.length > 0 ? nonZero : parts.slice(0, 1);
+};
+
+export const formatCountdownDuration = (
+  state: CountdownEventState,
+  now: Date,
+  showSeconds: boolean,
+  locale: string,
+  unitDisplay: Intl.NumberFormatOptions["unitDisplay"] = "short",
+) => {
+  return getCountdownDurationParts(state, now, showSeconds)
+    .map(({ unit, value }) => new Intl.NumberFormat(locale, { style: "unit", unit, unitDisplay }).format(value))
+    .join(" ");
+};

packages/widgets/src/countdown/index.ts

@@ -0,0 +1,24 @@
+import { IconHourglass } from "@tabler/icons-react";
+
+import { createWidgetDefinition } from "../definition";
+import { optionsBuilder } from "../options";
+import { getTimeZoneOptions } from "../clock/world-clock";
+
+const maximumCountdownEvents = 20;
+
+export const { definition, componentLoader } = createWidgetDefinition("countdown", {
+  icon: IconHourglass,
+  supportsAdvancedFocus: true,
+  createOptions() {
+    return optionsBuilder.from((factory) => ({
+      events: factory.dateTimeEventList({
+        defaultValue: [],
+        maxValues: maximumCountdownEvents,
+        timeZoneOptions: getTimeZoneOptions(),
+        withDescription: true,
+      }),
+      showProgress: factory.switch({ defaultValue: true }),
+      showSeconds: factory.switch({ defaultValue: false, withDescription: true }),
+    }));
+  },
+}).withDynamicImport(() => import("./component"));

packages/widgets/src/countdown/recurrence.spec.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from "vitest";
+
+import type { OptionDateTimeEvent } from "../options";
+import { getCountdownDurationParts } from "./display";
+import {
+  getCountdownEventState,
+  getCountdownProgress,
+  resolveWallDateTimeString,
+  groupCountdownStates,
+} from "./recurrence";
+
+const event = (overrides: Partial<OptionDateTimeEvent> = {}): OptionDateTimeEvent => ({
+  id: "event",
+  label: "Event",
+  targetUtc: "2026-07-15T13:00:00.000Z",
+  timeZone: "America/New_York",
+  recurrence: "none",
+  ...overrides,
+});
+
+describe("countdown recurrence", () => {
+  it("preserves a yearly event's wall-clock time across DST offsets", () => {
+    const recurring = event({ recurrence: "yearly" });
+    const winterState = getCountdownEventState(recurring, new Date("2027-01-01T00:00:00.000Z"));
+
+    expect(winterState.nextOccurrence?.toISOString()).toBe("2027-07-15T13:00:00.000Z");
+  });
+
+  it("skips non-leap years for a February 29 recurrence", () => {
+    const recurring = event({
+      recurrence: "yearly",
+      targetUtc: "2024-02-29T12:00:00.000Z",
+      timeZone: "UTC",
+    });
+    const state = getCountdownEventState(recurring, new Date("2025-01-01T00:00:00.000Z"));
+
+    expect(state.nextOccurrence?.toISOString()).toBe("2028-02-29T12:00:00.000Z");
+    expect(state.previousOccurrence?.toISOString()).toBe("2024-02-29T12:00:00.000Z");
+  });
+
+  it("selects the first valid time after a DST gap", () => {
+    const resolved = resolveWallDateTimeString("2026-03-08 02:30:45", "America/New_York");
+    expect(resolved?.toISOString()).toBe("2026-03-08T07:00:00.000Z");
+  });
+
+  it("selects the earlier occurrence when a wall-clock time repeats", () => {
+    const resolved = resolveWallDateTimeString("2026-11-01 01:30:00", "America/New_York");
+    expect(resolved?.toISOString()).toBe("2026-11-01T05:30:00.000Z");
+  });
+});
+
+describe("countdown ordering and progress", () => {
+  const now = new Date("2026-06-01T12:00:00.000Z");
+
+  it("preserves configured order within event groups", () => {
+    const states = [
+      getCountdownEventState(event({ id: "later", targetUtc: "2026-06-03T12:00:00.000Z" }), now),
+      getCountdownEventState(event({ id: "older", targetUtc: "2026-05-01T12:00:00.000Z" }), now),
+      getCountdownEventState(event({ id: "sooner", targetUtc: "2026-06-02T12:00:00.000Z" }), now),
+      getCountdownEventState(event({ id: "newer", targetUtc: "2026-05-31T12:00:00.000Z" }), now),
+    ];
+
+    const grouped = groupCountdownStates(states);
+    expect(grouped.upcoming.map(({ event: item }) => item.id)).toEqual(["later", "sooner"]);
+    expect(grouped.completed.map(({ event: item }) => item.id)).toEqual(["older", "newer"]);
+  });
+
+  it("clamps one-time progress and omits it without a start", () => {
+    const withStart = getCountdownEventState(
+      event({ targetUtc: "2026-06-02T12:00:00.000Z", startUtc: "2026-05-31T12:00:00.000Z" }),
+      now,
+    );
+    const withoutStart = getCountdownEventState(event({ targetUtc: "2026-06-02T12:00:00.000Z" }), now);
+
+    expect(getCountdownProgress(withStart, now)).toBe(50);
+    expect(getCountdownProgress(withStart, new Date("2026-06-04T12:00:00.000Z"))).toBe(100);
+    expect(getCountdownProgress(withoutStart, now)).toBeNull();
+  });
+
+  it("uses the previous and next occurrence for yearly progress", () => {
+    const state = getCountdownEventState(
+      event({ recurrence: "yearly", targetUtc: "2024-01-01T00:00:00.000Z", timeZone: "UTC" }),
+      new Date("2026-07-02T12:00:00.000Z"),
+    );
+    const progress = getCountdownProgress(state, new Date("2026-07-02T12:00:00.000Z"));
+
+    expect(progress).not.toBeNull();
+    if (progress === null) throw new Error("Expected yearly progress");
+    expect(progress).toBeGreaterThan(49);
+    expect(progress).toBeLessThan(51);
+  });
+
+  it("keeps seconds visible at every duration when enabled", () => {
+    const longState = getCountdownEventState(event({ targetUtc: "2026-06-03T13:00:00.000Z" }), now);
+    const shortState = getCountdownEventState(event({ targetUtc: "2026-06-02T11:30:45.000Z" }), now);
+
+    expect(getCountdownDurationParts(longState, now, true).some(({ unit }) => unit === "second")).toBe(true);
+    expect(getCountdownDurationParts(shortState, now, true).some(({ unit }) => unit === "second")).toBe(true);
+    expect(getCountdownDurationParts(longState, now, false).some(({ unit }) => unit === "second")).toBe(false);
+  });
+});

packages/widgets/src/countdown/recurrence.ts

@@ -0,0 +1,232 @@
+import dayjs from "dayjs";
+import timezone from "dayjs/plugin/timezone";
+import utc from "dayjs/plugin/utc";
+
+import type { OptionDateTimeEvent } from "../options";
+
+dayjs.extend(utc);
+dayjs.extend(timezone);
+
+const minuteMs = 60_000;
+const dayMs = 86_400_000;
+const timeZoneSupportCache = new Map<string, boolean>();
+
+export interface WallDateTime {
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  second: number;
+}
+
+export interface CountdownEventState {
+  event: OptionDateTimeEvent;
+  nextOccurrence: Date | null;
+  previousOccurrence: Date | null;
+  completed: boolean;
+  invalid: boolean;
+}
+
+export const isCountdownTimeZoneSupported = (timeZone: string) => {
+  const cached = timeZoneSupportCache.get(timeZone);
+  if (cached !== undefined) return cached;
+  try {
+    new Intl.DateTimeFormat("en", { timeZone }).format(0);
+    timeZoneSupportCache.set(timeZone, true);
+    return true;
+  } catch {
+    timeZoneSupportCache.set(timeZone, false);
+    return false;
+  }
+};
+
+export const parseWallDateTime = (value: string): WallDateTime | null => {
+  const match = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2})(?::(\d{2}))?$/.exec(value);
+  if (!match) return null;
+  const parts: WallDateTime = {
+    year: Number(match[1]),
+    month: Number(match[2]),
+    day: Number(match[3]),
+    hour: Number(match[4]),
+    minute: Number(match[5]),
+    second: Number(match[6] ?? 0),
+  };
+  const validationDate = new Date(
+    Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second),
+  );
+  if (
+    validationDate.getUTCFullYear() !== parts.year ||
+    validationDate.getUTCMonth() !== parts.month - 1 ||
+    validationDate.getUTCDate() !== parts.day ||
+    validationDate.getUTCHours() !== parts.hour ||
+    validationDate.getUTCMinutes() !== parts.minute ||
+    validationDate.getUTCSeconds() !== parts.second
+  ) {
+    return null;
+  }
+  return parts;
+};
+
+export const formatWallDateTime = (instant: string | Date, timeZone: string) => {
+  if (!isCountdownTimeZoneSupported(timeZone)) return "";
+  const value = dayjs(instant);
+  if (!value.isValid()) return "";
+  return value.tz(timeZone).format("YYYY-MM-DD HH:mm:ss");
+};
+
+const wallDateTimeEquals = (value: WallDateTime, candidate: dayjs.Dayjs) =>
+  candidate.year() === value.year &&
+  candidate.month() + 1 === value.month &&
+  candidate.date() === value.day &&
+  candidate.hour() === value.hour &&
+  candidate.minute() === value.minute &&
+  candidate.second() === value.second;
+
+const resolveExactWallDateTime = (value: WallDateTime, timeZone: string): Date[] => {
+  const naiveUtc = Date.UTC(value.year, value.month - 1, value.day, value.hour, value.minute, value.second);
+  const offsets = new Set<number>();
+  for (const dayOffset of [-2, -1, 0, 1, 2]) {
+    offsets.add(
+      dayjs
+        .utc(naiveUtc + dayOffset * dayMs)
+        .tz(timeZone)
+        .utcOffset(),
+    );
+  }
+
+  const matches: Date[] = [];
+  for (const offset of offsets) {
+    const candidate = new Date(naiveUtc - offset * minuteMs);
+    if (wallDateTimeEquals(value, dayjs(candidate).tz(timeZone))) matches.push(candidate);
+  }
+  // oxlint-disable-next-line unicorn/no-array-sort -- Array.toSorted is not supported in all target browsers.
+  return [...matches].sort((left, right) => left.getTime() - right.getTime());
+};
+
+/** Resolves a local wall-clock value, preferring the earlier repeated time and the first valid time after a DST gap. */
+export const resolveWallDateTime = (value: WallDateTime, timeZone: string): Date | null => {
+  if (!isCountdownTimeZoneSupported(timeZone)) return null;
+  const exactMatches = resolveExactWallDateTime(value, timeZone);
+  if (exactMatches[0]) return exactMatches[0];
+
+  const naiveUtc = Date.UTC(value.year, value.month - 1, value.day, value.hour, value.minute);
+  for (let minuteOffset = 1; minuteOffset <= 180; minuteOffset += 1) {
+    const candidateWallDate = new Date(naiveUtc + minuteOffset * minuteMs);
+    const candidateWall: WallDateTime = {
+      year: candidateWallDate.getUTCFullYear(),
+      month: candidateWallDate.getUTCMonth() + 1,
+      day: candidateWallDate.getUTCDate(),
+      hour: candidateWallDate.getUTCHours(),
+      minute: candidateWallDate.getUTCMinutes(),
+      second: candidateWallDate.getUTCSeconds(),
+    };
+    const matches = resolveExactWallDateTime(candidateWall, timeZone);
+    if (matches[0]) return matches[0];
+  }
+  return null;
+};
+
+export const resolveWallDateTimeString = (value: string, timeZone: string) => {
+  const wallDateTime = parseWallDateTime(value);
+  if (!wallDateTime) return null;
+  return resolveWallDateTime(wallDateTime, timeZone);
+};
+
+const isLeapYear = (year: number) => year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+
+const occurrenceForYear = (target: WallDateTime, year: number, timeZone: string) => {
+  if (target.month === 2 && target.day === 29 && !isLeapYear(year)) return null;
+  return resolveWallDateTime({ ...target, year }, timeZone);
+};
+
+const findYearlyOccurrence = (
+  target: WallDateTime,
+  timeZone: string,
+  startYear: number,
+  direction: 1 | -1,
+  predicate: (date: Date) => boolean,
+) => {
+  for (let index = 0; index < 12; index += 1) {
+    const occurrence = occurrenceForYear(target, startYear + index * direction, timeZone);
+    if (occurrence && predicate(occurrence)) return occurrence;
+  }
+  return null;
+};
+
+export const getCountdownEventState = (event: OptionDateTimeEvent, now: Date): CountdownEventState => {
+  const target = dayjs(event.targetUtc);
+  if (!target.isValid() || !isCountdownTimeZoneSupported(event.timeZone)) {
+    return { event, nextOccurrence: null, previousOccurrence: null, completed: false, invalid: true };
+  }
+
+  if (event.recurrence === "none") {
+    const targetDate = target.toDate();
+    const completed = targetDate.getTime() <= now.getTime();
+    return {
+      event,
+      nextOccurrence: completed ? null : targetDate,
+      previousOccurrence: completed ? targetDate : null,
+      completed,
+      invalid: false,
+    };
+  }
+
+  const targetWall = parseWallDateTime(formatWallDateTime(event.targetUtc, event.timeZone));
+  if (!targetWall) {
+    return { event, nextOccurrence: null, previousOccurrence: null, completed: false, invalid: true };
+  }
+  const currentYear = dayjs(now).tz(event.timeZone).year();
+  const nextOccurrence = findYearlyOccurrence(
+    targetWall,
+    event.timeZone,
+    currentYear,
+    1,
+    (occurrence) => occurrence.getTime() > now.getTime(),
+  );
+  const previousOccurrence = findYearlyOccurrence(
+    targetWall,
+    event.timeZone,
+    currentYear,
+    -1,
+    (occurrence) => occurrence.getTime() <= now.getTime(),
+  );
+  return {
+    event,
+    nextOccurrence,
+    previousOccurrence,
+    completed: false,
+    invalid: nextOccurrence === null,
+  };
+};
+
+export const getCountdownProgress = (state: CountdownEventState, now: Date): number | null => {
+  let start: Date | null = null;
+  let end: Date | null = null;
+
+  if (state.event.recurrence === "yearly") {
+    start = state.previousOccurrence;
+    end = state.nextOccurrence;
+  } else if (state.event.startUtc) {
+    const parsedStart = dayjs(state.event.startUtc);
+    const parsedEnd = dayjs(state.event.targetUtc);
+    if (parsedStart.isValid() && parsedEnd.isValid()) {
+      start = parsedStart.toDate();
+      end = parsedEnd.toDate();
+    }
+  }
+
+  if (!start || !end || end.getTime() <= start.getTime()) return null;
+  const progress = ((now.getTime() - start.getTime()) / (end.getTime() - start.getTime())) * 100;
+  return Math.min(100, Math.max(0, progress));
+};
+
+export const groupCountdownStates = (states: CountdownEventState[]) => {
+  const upcoming = states.filter((state) => state.nextOccurrence !== null && !state.invalid);
+  const completed = states.filter((state) => state.completed && state.previousOccurrence !== null && !state.invalid);
+  const invalid = states.filter((state) => state.invalid);
+  return { upcoming, completed, invalid };
+};
+
+export const getLatestReachedOccurrence = (event: OptionDateTimeEvent, now: Date) =>
+  getCountdownEventState(event, now).previousOccurrence;

packages/widgets/src/definition.spec.ts

@@ -38,7 +38,6 @@ describe("supportsAdvancedFocus", () => {
     beszelSystemGridDefinition,
     beszelSystemStatsDefinition,
     beszelSystemTableDefinition,
-    clockDefinition,
     customApiDefinition,
     dockerDefinition,
     indexerManagerDefinition,
@@ -49,6 +48,7 @@ describe("supportsAdvancedFocus", () => {
 
   test("requires an explicit opt-in", () => {
     expect(supportsAdvancedFocus({})).toBe(false);
+    expect(supportsAdvancedFocus(clockDefinition)).toBe(true);
     expect(supportsAdvancedFocus(downloadsDefinition)).toBe(true);
   });
 });

packages/widgets/src/errors/base-component.tsx

@@ -1,7 +1,5 @@
-import { useState } from "react";
 import { Anchor, Button, Stack, Text } from "@mantine/core";
 
-import { useSession } from "@homarr/auth/client";
 import type { stringOrTranslation } from "@homarr/translation";
 import { translateIfNecessary } from "@homarr/translation";
 import { useI18n } from "@homarr/translation/client";
@@ -17,22 +15,14 @@ export interface BaseWidgetErrorProps {
 
 export const BaseWidgetError = (props: BaseWidgetErrorProps) => {
   const t = useI18n();
-  const { data: session } = useSession();
-  const [errorTimestamp] = useState(Date.now);
 
   return (
     <Stack h="100%" align="center" justify="center" gap="md" data-homarr-widget-error>
       <props.icon size={40} />
       <Stack gap={0}>
         <Text ta="center">{translateIfNecessary(t, props.message)}</Text>
-        {props.showLogsLink && session?.user.permissions.includes("other-view-logs") && (
-          <Anchor
-            component={Link}
-            href={`/manage/tools/logs?focus=${errorTimestamp}`}
-            target="_blank"
-            ta="center"
-            size="sm"
-          >
+        {props.showLogsLink && (
+          <Anchor component={Link} href="/manage/tools/logs" target="_blank" ta="center" size="sm">
             {t("common.action.checkLogs")}
           </Anchor>
         )}

packages/widgets/src/errors/component.spec.ts

@@ -11,10 +11,6 @@ vi.mock("@homarr/translation/client", () => ({
   useI18n: () => (key: string) => key,
 }));
 
-vi.mock("@homarr/auth/client", () => ({
-  useSession: () => ({ data: null }),
-}));
-
 const matchMedia = (query: string) => ({
   matches: false,
   media: query,

packages/widgets/src/index.tsx

@@ -63,6 +63,10 @@ import * as beszelAlerts from "./beszel-alerts";
 import * as beszelSystemStats from "./beszel-system-stats";
 import * as video from "./video";
 import * as weather from "./weather";
+import * as today from "./today";
+import * as airQuality from "./air-quality";
+import * as countdown from "./countdown";
+import * as timer from "./timer";
 import * as customApi from "./custom-api";
 import * as assistant from "./assistant";
 import * as wud from "./wud";
@@ -94,6 +98,10 @@ export { AssistantWidgetRendererProvider } from "./assistant/context";
 export const widgetImports = {
   clock,
   weather,
+  today,
+  airQuality,
+  countdown,
+  timer,
   app,
   archiveTeamWarrior,
   anchorNote,

packages/widgets/src/manifest.spec.ts

@@ -17,6 +17,8 @@ import { widgetQueryRefetchIntervals } from "./refetch-intervals";
 import { widgetCatalogIcons } from "./catalog";
 import { getWidgetQueryKeys } from "./definition";
 
+const serializePollingPolicy = (entry: { queryKey: QueryKey; intervalSeconds: number | null }) => JSON.stringify(entry);
+
 describe("widget manifest promise stability", () => {
   it("returns the same module promise for every render", () => {
     expect(loadWidgetModule("clock")).toBe(loadWidgetModule("clock"));
@@ -145,9 +147,8 @@ describe("widget manifest promise stability", () => {
       }
     }
 
-    const serializePolicy = (entry: PollingPolicy) => JSON.stringify(entry);
-    expect(widgetQueryRefetchIntervals.map(serializePolicy).toSorted()).toEqual(
-      [...expectedByQueryKey.values()].map(serializePolicy).toSorted(),
+    expect(widgetQueryRefetchIntervals.map(serializePollingPolicy).toSorted()).toEqual(
+      [...expectedByQueryKey.values()].map(serializePollingPolicy).toSorted(),
     );
   });
 

packages/widgets/src/manifest.ts

@@ -24,6 +24,10 @@ export type WidgetResources = {
 const moduleLoaders: Record<WidgetKind, () => Promise<WidgetModule>> = {
   clock: () => import("./clock") as Promise<WidgetModule>,
   weather: () => import("./weather") as Promise<WidgetModule>,
+  today: () => import("./today") as Promise<WidgetModule>,
+  airQuality: () => import("./air-quality") as Promise<WidgetModule>,
+  countdown: () => import("./countdown") as Promise<WidgetModule>,
+  timer: () => import("./timer") as Promise<WidgetModule>,
   app: () => import("./app") as Promise<WidgetModule>,
   assistant: () => import("./assistant") as Promise<WidgetModule>,
   archiveTeamWarrior: () => import("./archive-team-warrior") as Promise<WidgetModule>,
@@ -85,6 +89,10 @@ const moduleLoaders: Record<WidgetKind, () => Promise<WidgetModule>> = {
 const componentLoaders: Record<WidgetKind, () => Promise<WidgetComponentModule>> = {
   clock: () => import("./clock/component") as Promise<WidgetComponentModule>,
   weather: () => import("./weather/component") as Promise<WidgetComponentModule>,
+  today: () => import("./today/component") as Promise<WidgetComponentModule>,
+  airQuality: () => import("./air-quality/component") as Promise<WidgetComponentModule>,
+  countdown: () => import("./countdown/component") as Promise<WidgetComponentModule>,
+  timer: () => import("./timer/component") as Promise<WidgetComponentModule>,
   app: () => import("./app/component") as Promise<WidgetComponentModule>,
   assistant: () => import("./assistant/component") as Promise<WidgetComponentModule>,
   archiveTeamWarrior: () => import("./archive-team-warrior/component") as Promise<WidgetComponentModule>,

packages/widgets/src/options.ts

@@ -52,6 +52,7 @@ interface SelectInput<TOptions extends readonly SelectOption[]> extends CommonIn
 > {
   options: TOptions;
   searchable?: boolean;
+  withPlaceholder?: boolean;
 }
 
 interface DynamicSelectInput extends CommonInput<DynamicSelectOption | null> {
@@ -107,6 +108,34 @@ interface SliderInput extends CommonInput<number> {
   step?: number;
 }
 
+export interface OptionTimezone {
+  id: string;
+  label: string;
+  timeZone: string;
+}
+
+interface TimezoneListInput extends CommonInput<OptionTimezone[]> {
+  maxValues?: number;
+  presets?: readonly OptionTimezone[];
+  timeZoneOptions: readonly { value: string; label: string }[];
+}
+
+export type DateTimeEventRecurrence = "none" | "yearly";
+
+export interface OptionDateTimeEvent {
+  id: string;
+  label: string;
+  targetUtc: string;
+  timeZone: string;
+  startUtc?: string;
+  recurrence: DateTimeEventRecurrence;
+}
+
+interface DateTimeEventListInput extends CommonInput<OptionDateTimeEvent[]> {
+  maxValues?: number;
+  timeZoneOptions: readonly { value: string; label: string }[];
+}
+
 export interface OptionLocation {
   name: string;
   latitude: number;
@@ -163,6 +192,7 @@ const optionsFactory = {
     options: input.options,
     searchable: input.searchable ?? false,
     withDescription: input.withDescription ?? false,
+    withPlaceholder: input.withPlaceholder ?? false,
   }),
   number: (input: NumberInput) => ({
     type: "number" as const,
@@ -192,6 +222,72 @@ const optionsFactory = {
       longitude: z.number(),
     }),
   }),
+  timezoneList: (input: TimezoneListInput) => {
+    const maxValues = input.maxValues ?? 6;
+    return {
+      type: "timezoneList" as const,
+      defaultValue: input.defaultValue ?? [],
+      maxValues,
+      presets: input.presets ?? [],
+      timeZoneOptions: input.timeZoneOptions,
+      withDescription: input.withDescription ?? false,
+      validate: z
+        .array(
+          z.object({
+            id: z.string().min(1),
+            label: z.string().trim().min(1).max(64),
+            timeZone: z.string().min(1),
+          }),
+        )
+        .max(maxValues)
+        .superRefine((values, ctx) => {
+          const ids = new Set<string>();
+          const timeZones = new Set<string>();
+
+          values.forEach((value, index) => {
+            if (ids.has(value.id)) {
+              ctx.addIssue({ code: "custom", path: [index, "id"], message: "Duplicate identifier" });
+            }
+            if (timeZones.has(value.timeZone)) {
+              ctx.addIssue({ code: "custom", path: [index, "timeZone"], message: "Duplicate timezone" });
+            }
+            ids.add(value.id);
+            timeZones.add(value.timeZone);
+          });
+        }),
+    };
+  },
+  dateTimeEventList: (input: DateTimeEventListInput) => {
+    const maxValues = input.maxValues ?? 20;
+    const dateTimeEventSchema = z.object({
+      id: z.string().min(1),
+      label: z.string().trim().min(1).max(64),
+      targetUtc: z.iso.datetime(),
+      timeZone: z.string().min(1),
+      startUtc: z.iso.datetime().optional(),
+      recurrence: z.enum(["none", "yearly"]),
+    });
+
+    return {
+      type: "dateTimeEventList" as const,
+      defaultValue: input.defaultValue ?? [],
+      maxValues,
+      timeZoneOptions: input.timeZoneOptions,
+      withDescription: input.withDescription ?? false,
+      validate: z
+        .array(dateTimeEventSchema)
+        .max(maxValues)
+        .superRefine((values, ctx) => {
+          const ids = new Set<string>();
+          values.forEach((value, index) => {
+            if (ids.has(value.id)) {
+              ctx.addIssue({ code: "custom", path: [index, "id"], message: "Duplicate identifier" });
+            }
+            ids.add(value.id);
+          });
+        }),
+    };
+  },
   multiText: (input?: CommonInput<string[]> & { validate?: ZodType }) => ({
     type: "multiText" as const,
     defaultValue: input?.defaultValue ?? [],

packages/widgets/src/refetch-intervals.ts

@@ -13,6 +13,8 @@ export const widgetQueryRefetchIntervals = [
   { queryKey: [["widget", "healthMonitoring"]], intervalSeconds: 10 },
   { queryKey: [["widget", "mediaServer", "getCurrentStreams"]], intervalSeconds: 10 },
   { queryKey: [["widget", "tracearr"]], intervalSeconds: 10 },
+  { queryKey: [["widget", "weather", "atLocation"]], intervalSeconds: 600 },
+  { queryKey: [["widget", "airQuality", "atLocation"]], intervalSeconds: 900 },
   { queryKey: [["widget", "immich", "getAlbum"]], intervalSeconds: null },
   { queryKey: [["widget", "immich", "getServerStats"]], intervalSeconds: null },
   { queryKey: [["widget", "immich", "getAlbums"]], intervalSeconds: null },

packages/widgets/src/timer/component.tsx

@@ -0,0 +1,628 @@
+"use client";
+
+import type { CSSProperties } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  ActionIcon,
+  Alert,
+  Badge,
+  Group,
+  Paper,
+  Progress,
+  ScrollArea,
+  SimpleGrid,
+  Stack,
+  Switch,
+  Text,
+  Tooltip,
+} from "@mantine/core";
+import { useMediaQuery, useReducedMotion } from "@mantine/hooks";
+import { IconBell, IconPlayerPause, IconPlayerPlay, IconRefresh, IconSettings, IconVolume } from "@tabler/icons-react";
+import { useTiks } from "@rexa-developer/tiks/react";
+
+import { useScopedI18n } from "@homarr/translation/client";
+
+import {
+  claimBrowserAlertOccurrence,
+  getBrowserNotificationPermission,
+  requestBrowserNotificationPermission,
+  showBrowserNotification,
+} from "../common/browser-alert";
+import { useLocalWidgetState } from "../common/use-local-widget-state";
+import { useWidgetNow } from "../common/use-widget-now";
+import type { WidgetComponentProps } from "../definition";
+import {
+  createTimerRuntime,
+  getRemainingMs,
+  isTimerRuntimeState,
+  migrateTimerRuntimeState,
+  pauseTimerRuntime,
+  reconcileTimerRuntime,
+  resetTimerRuntime,
+  setTimerAlertPreference,
+  startTimerRuntime,
+  synchronizeTimerRuntime,
+} from "./runtime";
+import type { TimerDurations, TimerRuntimeState } from "./runtime";
+
+const completionSoundCount = 5;
+const completionSoundIntervalMs = 300;
+
+export default function TimerWidget({
+  boardId,
+  displayMode,
+  height,
+  isEditMode,
+  itemId,
+  options,
+  width,
+}: WidgetComponentProps<"timer">) {
+  const now = useWidgetNow("second");
+  const t = useScopedI18n("widget.timer");
+  const reducedMotion = useReducedMotion();
+  const forcedColors = useMediaQuery("(forced-colors: active)") ?? false;
+  const { click: playResetSound, toggle: playRunningSound } = useTiks({
+    theme: "soft",
+    volume: 0.12,
+    respectReducedMotion: true,
+  });
+  const { notify: playCompletionSound } = useTiks({
+    theme: "glass",
+    volume: 0.12,
+    respectReducedMotion: true,
+  });
+  const durations = useMemo<TimerDurations>(
+    () => ({
+      timerMinutes: options.timerMinutes,
+      focusMinutes: options.focusMinutes,
+      shortBreakMinutes: options.shortBreakMinutes,
+      longBreakMinutes: options.longBreakMinutes,
+      sessionsBeforeLongBreak: options.sessionsBeforeLongBreak,
+      autoStartBreaks: options.autoStartBreaks,
+      autoStartFocus: options.autoStartFocus,
+    }),
+    [
+      options.autoStartBreaks,
+      options.autoStartFocus,
+      options.focusMinutes,
+      options.longBreakMinutes,
+      options.sessionsBeforeLongBreak,
+      options.shortBreakMinutes,
+      options.timerMinutes,
+    ],
+  );
+  const storagePrefix = boardId && itemId ? `homarr:timer:${boardId}:${itemId}` : undefined;
+  const [runtime, setRuntime] = useLocalWidgetState<TimerRuntimeState>({
+    key: storagePrefix ? `${storagePrefix}:state` : undefined,
+    version: 3,
+    defaultValue: () => createTimerRuntime(options.mode, durations),
+    validate: isTimerRuntimeState,
+    migrate: migrateTimerRuntimeState,
+  });
+  const [notificationPermission, setNotificationPermission] = useState(() => getBrowserNotificationPermission());
+  const [attentionFlash, setAttentionFlash] = useState(false);
+  const historyInitializedRef = useRef(false);
+  const handledHistoryIdRef = useRef<string | null>(null);
+  const completionSoundTimeoutRef = useRef<number | null>(null);
+  const attentionFlashTimeoutRef = useRef<number | null>(null);
+  const stopCompletionSoundSequence = useCallback(() => {
+    if (completionSoundTimeoutRef.current !== null) {
+      window.clearTimeout(completionSoundTimeoutRef.current);
+      completionSoundTimeoutRef.current = null;
+    }
+    if (attentionFlashTimeoutRef.current !== null) {
+      window.clearTimeout(attentionFlashTimeoutRef.current);
+      attentionFlashTimeoutRef.current = null;
+    }
+    setAttentionFlash(false);
+  }, []);
+  const flashAttention = useCallback(() => {
+    if (attentionFlashTimeoutRef.current !== null) {
+      window.clearTimeout(attentionFlashTimeoutRef.current);
+    }
+    setAttentionFlash(true);
+    attentionFlashTimeoutRef.current = window.setTimeout(() => {
+      attentionFlashTimeoutRef.current = null;
+      setAttentionFlash(false);
+    }, 180);
+  }, []);
+
+  useEffect(() => {
+    setRuntime((current) => synchronizeTimerRuntime(current, options.mode, durations));
+  }, [durations, options.mode, setRuntime]);
+
+  useEffect(() => {
+    if (!now) return;
+    setRuntime((current) => reconcileTimerRuntime(current, now.getTime(), durations));
+  }, [durations, now, setRuntime]);
+
+  useEffect(() => {
+    const latest = runtime.history.at(-1);
+    if (!historyInitializedRef.current) {
+      historyInitializedRef.current = true;
+      handledHistoryIdRef.current = latest?.id ?? null;
+      return;
+    }
+    if (!latest || handledHistoryIdRef.current === latest.id) return;
+    handledHistoryIdRef.current = latest.id;
+
+    const alertKey = storagePrefix ? `${storagePrefix}:alerted-completions` : undefined;
+    if (alertKey && !claimBrowserAlertOccurrence(alertKey, latest.id)) return;
+    if (runtime.alerts.notifications) {
+      showBrowserNotification({
+        title: t("alert.title"),
+        body: t("alert.completed", { phase: t(`phase.${latest.phase}`) }),
+        tag: latest.id,
+      });
+    }
+    if (!runtime.alerts.sound) return;
+    stopCompletionSoundSequence();
+    playCompletionSound();
+    if (!runtime.awaitingManualStart) return;
+    flashAttention();
+
+    let remainingSounds = completionSoundCount - 1;
+    const playNextSound = () => {
+      completionSoundTimeoutRef.current = window.setTimeout(() => {
+        completionSoundTimeoutRef.current = null;
+        playCompletionSound();
+        flashAttention();
+        remainingSounds -= 1;
+        if (remainingSounds > 0) playNextSound();
+      }, completionSoundIntervalMs);
+    };
+    playNextSound();
+  }, [
+    playCompletionSound,
+    flashAttention,
+    runtime.alerts.notifications,
+    runtime.alerts.sound,
+    runtime.awaitingManualStart,
+    runtime.history,
+    stopCompletionSoundSequence,
+    storagePrefix,
+    t,
+  ]);
+
+  useEffect(() => {
+    if (runtime.awaitingManualStart && runtime.alerts.sound) return;
+    stopCompletionSoundSequence();
+  }, [runtime.alerts.sound, runtime.awaitingManualStart, stopCompletionSoundSequence]);
+
+  useEffect(() => stopCompletionSoundSequence, [stopCompletionSoundSequence]);
+
+  if (!now) {
+    return (
+      <Stack h="100%" align="center" justify="center">
+        <Text c="dimmed">—</Text>
+      </Stack>
+    );
+  }
+
+  const nowMs = now.getTime();
+  const remainingMs = getRemainingMs(runtime, nowMs);
+  const phaseDurationMs = runtime.totalDurationMs;
+  let progress = 0;
+  if (phaseDurationMs > 0) {
+    progress = Math.min(100, Math.max(0, ((phaseDurationMs - remainingMs) / phaseDurationMs) * 100));
+  }
+  const controlSize = getTimerControlSize(width, height, displayMode);
+  const attentionStyle = getTimerAttentionStyle({
+    awaitingManualStart: runtime.awaitingManualStart,
+    flash: attentionFlash,
+    forcedColors,
+    reducedMotion,
+  });
+  const toggleRunning = () => {
+    if (runtime.alerts.sound) playRunningSound(runtime.status !== "running");
+    if (runtime.status === "running") {
+      setRuntime((current) => pauseTimerRuntime(current, nowMs));
+      return;
+    }
+    setRuntime((current) => startTimerRuntime(current, nowMs, durations));
+  };
+  const reset = () => {
+    if (runtime.alerts.sound) playResetSound();
+    setRuntime((current) => resetTimerRuntime(current, durations));
+  };
+  const setNotifications = async (enabled: boolean) => {
+    if (!enabled) {
+      setRuntime((current) => setTimerAlertPreference(current, "notifications", false));
+      return;
+    }
+    const permission = await requestBrowserNotificationPermission();
+    setNotificationPermission(permission);
+    if (permission === "granted") {
+      setRuntime((current) => setTimerAlertPreference(current, "notifications", true));
+    }
+  };
+  const setSound = (enabled: boolean) => {
+    playRunningSound(enabled);
+    setRuntime((current) => setTimerAlertPreference(current, "sound", enabled));
+  };
+
+  const shared = {
+    disabled: isEditMode,
+    attentionStyle,
+    controlSize,
+    height,
+    onReset: reset,
+    onToggleRunning: toggleRunning,
+    progress,
+    remainingMs,
+    runtime,
+    width,
+  };
+
+  if (displayMode !== "advanced") return <CompactTimer {...shared} />;
+
+  return (
+    <AdvancedTimer
+      {...shared}
+      durations={durations}
+      notificationPermission={notificationPermission}
+      onNotificationsChange={setNotifications}
+      onSoundChange={setSound}
+    />
+  );
+}
+
+type TimerControlSize = "sm" | "md" | "lg";
+
+interface TimerDisplayProps {
+  attentionStyle: CSSProperties;
+  controlSize: TimerControlSize;
+  disabled: boolean;
+  height: number;
+  onReset: () => void;
+  onToggleRunning: () => void;
+  progress: number;
+  remainingMs: number;
+  runtime: TimerRuntimeState;
+  width: number;
+}
+
+const CompactTimer = ({
+  attentionStyle,
+  controlSize,
+  disabled,
+  height,
+  onReset,
+  onToggleRunning,
+  progress,
+  remainingMs,
+  runtime,
+  width,
+}: TimerDisplayProps) => {
+  const t = useScopedI18n("widget.timer");
+  const phaseLabel = getTimerPhaseLabel(runtime, t);
+  const showCompletedFocus = runtime.mode === "pomodoro" && width >= 320;
+  const showProgress = height >= 125;
+  let phaseBadgeMaxWidth = "calc(100% - var(--mantine-spacing-md))";
+  if (showCompletedFocus) phaseBadgeMaxWidth = "60%";
+  return (
+    <Stack
+      h="100%"
+      w="100%"
+      align="center"
+      justify="center"
+      gap="xs"
+      p="xs"
+      style={{ ...attentionStyle, overflow: "hidden", position: "relative" }}
+    >
+      <Badge
+        variant="light"
+        size="xs"
+        h="auto"
+        maw={phaseBadgeMaxWidth}
+        py="calc(var(--mantine-spacing-xs) / 2)"
+        aria-live="polite"
+        style={{
+          insetInlineStart: "var(--mantine-spacing-xs)",
+          position: "absolute",
+          top: "var(--mantine-spacing-xs)",
+        }}
+        styles={{
+          label: {
+            lineHeight: "var(--mantine-line-height-xs)",
+            overflow: "visible",
+            textOverflow: "clip",
+            whiteSpace: "normal",
+          },
+        }}
+      >
+        {phaseLabel}
+      </Badge>
+      {showCompletedFocus && (
+        <Text
+          size="xs"
+          c="dimmed"
+          style={{
+            insetInlineEnd: "var(--mantine-spacing-xs)",
+            position: "absolute",
+            top: "var(--mantine-spacing-xs)",
+          }}
+        >
+          {t("compact.completedFocus", { count: runtime.completedFocusSessions })}
+        </Text>
+      )}
+      <Text component="time" fz="xl" fw={700} lh={1} style={{ fontVariantNumeric: "tabular-nums" }}>
+        {formatTimerDuration(remainingMs)}
+      </Text>
+      {showProgress && (
+        <Progress w="100%" value={progress} aria-label={t("progress", { progress: Math.round(progress) })} />
+      )}
+      <TimerControls
+        controlSize={controlSize}
+        disabled={disabled}
+        isRunning={runtime.status === "running"}
+        onReset={onReset}
+        onToggleRunning={onToggleRunning}
+      />
+    </Stack>
+  );
+};
+
+interface AdvancedTimerProps extends TimerDisplayProps {
+  durations: TimerDurations;
+  notificationPermission: ReturnType<typeof getBrowserNotificationPermission>;
+  onNotificationsChange: (enabled: boolean) => Promise<void>;
+  onSoundChange: (enabled: boolean) => void;
+}
+
+const AdvancedTimer = ({
+  attentionStyle,
+  controlSize,
+  disabled,
+  durations,
+  notificationPermission,
+  onNotificationsChange,
+  onReset,
+  onSoundChange,
+  onToggleRunning,
+  progress,
+  remainingMs,
+  runtime,
+}: AdvancedTimerProps) => {
+  const t = useScopedI18n("widget.timer");
+  const phaseLabel = getTimerPhaseLabel(runtime, t);
+  return (
+    <ScrollArea h="100%" w="100%" type="auto" offsetScrollbars scrollbarSize={6}>
+      <Stack gap="md" p="md">
+        <Paper
+          withBorder
+          p="lg"
+          style={{
+            ...attentionStyle,
+            background:
+              "linear-gradient(145deg, var(--mantine-primary-color-light), var(--mantine-color-secondaryColor-light))",
+          }}
+        >
+          <Stack align="center" gap="sm">
+            <Badge variant="light" size="sm" aria-live="polite">
+              {phaseLabel}
+            </Badge>
+            <Text
+              component="time"
+              fz="var(--mantine-h1-font-size)"
+              fw={700}
+              lh={1}
+              style={{ fontVariantNumeric: "tabular-nums" }}
+            >
+              {formatTimerDuration(remainingMs)}
+            </Text>
+            <Progress w="100%" value={progress} aria-label={t("progress", { progress: Math.round(progress) })} />
+            <TimerControls
+              controlSize={controlSize}
+              disabled={disabled}
+              isRunning={runtime.status === "running"}
+              onReset={onReset}
+              onToggleRunning={onToggleRunning}
+            />
+          </Stack>
+        </Paper>
+
+        {runtime.mode === "pomodoro" && <PomodoroSequence runtime={runtime} durations={durations} />}
+
+        <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md">
+          <Paper withBorder p="md">
+            <Group gap="xs" mb="sm">
+              <IconSettings size={18} aria-hidden />
+              <Text fw={600}>{t("advanced.settings")}</Text>
+            </Group>
+            <SettingsSummary mode={runtime.mode} durations={durations} />
+            <Text size="xs" c="dimmed" mt="sm">
+              {t("advanced.settingsHint")}
+            </Text>
+          </Paper>
+
+          <Paper withBorder p="md">
+            <Group gap="xs" mb="sm">
+              <IconBell size={18} aria-hidden />
+              <Text fw={600}>{t("advanced.localAlerts")}</Text>
+            </Group>
+            <Stack gap="sm">
+              <Switch
+                checked={runtime.alerts.notifications && notificationPermission === "granted"}
+                disabled={disabled || notificationPermission === "unsupported" || notificationPermission === "denied"}
+                label={t("advanced.notifications")}
+                onChange={(event) => void onNotificationsChange(event.currentTarget.checked)}
+              />
+              <Switch
+                checked={runtime.alerts.sound}
+                disabled={disabled}
+                label={t("advanced.sound")}
+                onChange={(event) => onSoundChange(event.currentTarget.checked)}
+                thumbIcon={<IconVolume size={12} />}
+              />
+              <Text size="xs" c="dimmed">
+                {t("advanced.localAlertsHint")}
+              </Text>
+              {notificationPermission === "denied" && <Alert color="yellow">{t("advanced.notificationsDenied")}</Alert>}
+            </Stack>
+          </Paper>
+        </SimpleGrid>
+      </Stack>
+    </ScrollArea>
+  );
+};
+
+const TimerControls = ({
+  controlSize,
+  disabled,
+  isRunning,
+  onReset,
+  onToggleRunning,
+}: {
+  controlSize: TimerControlSize;
+  disabled: boolean;
+  isRunning: boolean;
+  onReset: () => void;
+  onToggleRunning: () => void;
+}) => {
+  const t = useScopedI18n("widget.timer");
+  const toggleLabel = isRunning ? t("action.pause") : t("action.start");
+  return (
+    <Group gap="xs" wrap="nowrap">
+      <Tooltip label={toggleLabel}>
+        <ActionIcon
+          size={controlSize}
+          variant="filled"
+          disabled={disabled}
+          onClick={onToggleRunning}
+          aria-label={toggleLabel}
+        >
+          {isRunning ? <IconPlayerPause /> : <IconPlayerPlay />}
+        </ActionIcon>
+      </Tooltip>
+      <Tooltip label={t("action.reset")}>
+        <ActionIcon
+          size={controlSize}
+          variant="light"
+          disabled={disabled}
+          onClick={onReset}
+          aria-label={t("action.reset")}
+        >
+          <IconRefresh />
+        </ActionIcon>
+      </Tooltip>
+    </Group>
+  );
+};
+
+type ScopedTimerTranslator = ReturnType<typeof useScopedI18n<"widget.timer">>;
+
+const getTimerPhaseLabel = (runtime: TimerRuntimeState, t: ScopedTimerTranslator) => {
+  const phase = t(`phase.${runtime.phase}`);
+  if (!runtime.awaitingManualStart) return phase;
+  if (runtime.mode === "timer") return t("attention.timerComplete");
+  return t("attention.phaseReady", { phase });
+};
+
+const getTimerControlSize = (
+  width: number,
+  height: number,
+  displayMode: "compact" | "advanced" | undefined,
+): TimerControlSize => {
+  if (displayMode === "advanced") return "lg";
+  if (width < 150 || height < 115) return "sm";
+  if (width < 220 || height < 150) return "md";
+  return "lg";
+};
+
+const getTimerAttentionStyle = ({
+  awaitingManualStart,
+  flash,
+  forcedColors,
+  reducedMotion,
+}: {
+  awaitingManualStart: boolean;
+  flash: boolean;
+  forcedColors: boolean;
+  reducedMotion: boolean;
+}): CSSProperties => {
+  if (forcedColors && awaitingManualStart) {
+    return {
+      outline: "0.125rem solid Highlight",
+      outlineOffset: "0.125rem",
+    };
+  }
+  if (reducedMotion && awaitingManualStart) {
+    return {
+      boxShadow:
+        "inset 0 0 1rem 0.125rem color-mix(in srgb, var(--mantine-color-secondaryColor-filled) 45%, transparent)",
+    };
+  }
+  if (!flash) {
+    return {
+      boxShadow: "none",
+      transition: "box-shadow 0.12s ease-out",
+    };
+  }
+  return {
+    boxShadow:
+      "inset 0 0 1rem 0.125rem color-mix(in srgb, var(--mantine-color-secondaryColor-filled) 45%, transparent), 0 0 3rem 0.875rem color-mix(in srgb, var(--mantine-color-secondaryColor-filled) 40%, transparent)",
+    transition: "box-shadow 0.12s ease-out",
+  };
+};
+
+const PomodoroSequence = ({ runtime, durations }: { runtime: TimerRuntimeState; durations: TimerDurations }) => {
+  const t = useScopedI18n("widget.timer");
+  return (
+    <Paper withBorder p="md">
+      <Text fw={600} mb="xs">
+        {t("advanced.sequence")}
+      </Text>
+      <Group gap="xs" wrap="wrap">
+        {Array.from({ length: durations.sessionsBeforeLongBreak }, (_, index) => (
+          <Group key={index} gap={4} wrap="nowrap">
+            <Badge variant={index < runtime.completedFocusSessions ? "filled" : "light"}>
+              {t("advanced.focusSession", { session: index + 1 })}
+            </Badge>
+            <Text size="xs" c="dimmed">
+              {t("phase.shortBreak")}
+            </Text>
+          </Group>
+        ))}
+        <Badge color="violet" variant={runtime.phase === "longBreak" ? "filled" : "light"}>
+          {t("phase.longBreak")}
+        </Badge>
+      </Group>
+    </Paper>
+  );
+};
+
+const SettingsSummary = ({ mode, durations }: { mode: TimerRuntimeState["mode"]; durations: TimerDurations }) => {
+  const t = useScopedI18n("widget.timer");
+  if (mode === "timer") return <SettingLine label={t("option.timerMinutes.label")} value={durations.timerMinutes} />;
+  return (
+    <Stack gap={5}>
+      <SettingLine label={t("option.focusMinutes.label")} value={durations.focusMinutes} />
+      <SettingLine label={t("option.shortBreakMinutes.label")} value={durations.shortBreakMinutes} />
+      <SettingLine label={t("option.longBreakMinutes.label")} value={durations.longBreakMinutes} />
+      <SettingLine label={t("option.sessionsBeforeLongBreak.label")} value={durations.sessionsBeforeLongBreak} />
+    </Stack>
+  );
+};
+
+const SettingLine = ({ label, value }: { label: string; value: number }) => (
+  <Group justify="space-between" gap="md" wrap="nowrap">
+    <Text size="sm" c="dimmed">
+      {label}
+    </Text>
+    <Text size="sm" fw={600}>
+      {value}
+    </Text>
+  </Group>
+);
+
+export const formatTimerDuration = (durationMs: number): string => {
+  const totalSeconds = Math.max(0, Math.ceil(durationMs / 1_000));
+  const hours = Math.floor(totalSeconds / 3_600);
+  const minutes = Math.floor((totalSeconds % 3_600) / 60);
+  const seconds = totalSeconds % 60;
+  const minuteText = String(minutes).padStart(2, "0");
+  const secondText = String(seconds).padStart(2, "0");
+  if (hours === 0) return `${minuteText}:${secondText}`;
+  return `${String(hours).padStart(2, "0")}:${minuteText}:${secondText}`;
+};

packages/widgets/src/timer/index.ts

@@ -0,0 +1,54 @@
+import { IconClockPlay } from "@tabler/icons-react";
+import { z } from "zod/v4";
+
+import { createWidgetDefinition } from "../definition";
+import { optionsBuilder } from "../options";
+
+export const { definition, componentLoader } = createWidgetDefinition("timer", {
+  icon: IconClockPlay,
+  supportsAdvancedFocus: true,
+  createOptions() {
+    return optionsBuilder.from(
+      (factory) => ({
+        mode: factory.select({
+          defaultValue: "pomodoro",
+          options: [
+            { value: "timer", label: (t) => t("widget.timer.option.mode.options.timer") },
+            { value: "pomodoro", label: (t) => t("widget.timer.option.mode.options.pomodoro") },
+          ],
+        }),
+        timerMinutes: factory.number({
+          defaultValue: 10,
+          validate: z.number().int().min(1).max(1440),
+        }),
+        focusMinutes: factory.number({
+          defaultValue: 25,
+          validate: z.number().int().min(1).max(180),
+        }),
+        shortBreakMinutes: factory.number({
+          defaultValue: 5,
+          validate: z.number().int().min(1).max(60),
+        }),
+        longBreakMinutes: factory.number({
+          defaultValue: 15,
+          validate: z.number().int().min(1).max(180),
+        }),
+        sessionsBeforeLongBreak: factory.number({
+          defaultValue: 4,
+          validate: z.number().int().min(1).max(12),
+        }),
+        autoStartBreaks: factory.switch({ defaultValue: false }),
+        autoStartFocus: factory.switch({ defaultValue: false }),
+      }),
+      {
+        timerMinutes: { shouldHide: ({ mode }) => mode !== "timer" },
+        focusMinutes: { shouldHide: ({ mode }) => mode !== "pomodoro" },
+        shortBreakMinutes: { shouldHide: ({ mode }) => mode !== "pomodoro" },
+        longBreakMinutes: { shouldHide: ({ mode }) => mode !== "pomodoro" },
+        sessionsBeforeLongBreak: { shouldHide: ({ mode }) => mode !== "pomodoro" },
+        autoStartBreaks: { shouldHide: ({ mode }) => mode !== "pomodoro" },
+        autoStartFocus: { shouldHide: ({ mode }) => mode !== "pomodoro" },
+      },
+    );
+  },
+}).withDynamicImport(() => import("./component"));

packages/widgets/src/timer/runtime.spec.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  createTimerRuntime,
+  getRemainingMs,
+  isTimerRuntimeState,
+  pauseTimerRuntime,
+  reconcileTimerRuntime,
+  startTimerRuntime,
+  synchronizeTimerRuntime,
+} from "./runtime";
+
+const durations = {
+  timerMinutes: 10,
+  focusMinutes: 25,
+  shortBreakMinutes: 5,
+  longBreakMinutes: 15,
+  sessionsBeforeLongBreak: 2,
+  autoStartBreaks: false,
+  autoStartFocus: false,
+};
+
+describe("timer runtime", () => {
+  it("uses a persisted deadline and preserves a paused remainder", () => {
+    const initial = createTimerRuntime("timer", durations);
+    const running = startTimerRuntime(initial, 1_000, durations);
+    expect(running.deadline).toBe(601_000);
+    expect(getRemainingMs(running, 61_000)).toBe(540_000);
+
+    const paused = pauseTimerRuntime(running, 61_000);
+    expect(paused).toMatchObject({ status: "paused", remainingMs: 540_000, deadline: null });
+    expect(startTimerRuntime(paused, 100_000, durations).deadline).toBe(640_000);
+  });
+
+  it("moves through short and long breaks using completed focus sessions", () => {
+    const firstFocus = startTimerRuntime(createTimerRuntime("pomodoro", durations), 0, durations);
+    const shortBreak = reconcileTimerRuntime(firstFocus, 25 * 60_000, durations);
+    expect(shortBreak).toMatchObject({ phase: "shortBreak", status: "idle", completedFocusSessions: 1 });
+
+    const secondFocus = startTimerRuntime(
+      { ...shortBreak, phase: "focus", remainingMs: 25 * 60_000 },
+      2_000_000,
+      durations,
+    );
+    const longBreak = reconcileTimerRuntime(secondFocus, 3_500_000, durations);
+    expect(longBreak).toMatchObject({ phase: "longBreak", status: "idle", completedFocusSessions: 2 });
+  });
+
+  it("catches up chained automatic phases from their original deadlines", () => {
+    const automatic = {
+      ...durations,
+      focusMinutes: 1,
+      shortBreakMinutes: 1,
+      autoStartBreaks: true,
+      autoStartFocus: true,
+    };
+    const running = startTimerRuntime(createTimerRuntime("pomodoro", automatic), 0, automatic);
+    const reconciled = reconcileTimerRuntime(running, 125_000, automatic);
+
+    expect(reconciled).toMatchObject({ phase: "focus", status: "running", completedFocusSessions: 1 });
+    expect(reconciled.deadline).toBe(180_000);
+    expect(reconciled.history).toHaveLength(2);
+  });
+
+  it("keeps only the latest 20 completions", () => {
+    let state = startTimerRuntime(createTimerRuntime("timer", { ...durations, timerMinutes: 1 }), 0, durations);
+    for (let index = 1; index <= 25; index += 1) {
+      state = reconcileTimerRuntime(state, index * 60_000, { ...durations, timerMinutes: 1 });
+      state = startTimerRuntime(state, index * 60_000, { ...durations, timerMinutes: 1 });
+    }
+    expect(state.history).toHaveLength(20);
+  });
+
+  it("resets only live state when the permanent mode changes", () => {
+    const initial = createTimerRuntime("timer", durations);
+    const withHistory = {
+      ...initial,
+      history: [{ id: "timer:1", phase: "timer" as const, completedAt: 1, durationMs: 1 }],
+    };
+    const synchronized = synchronizeTimerRuntime(withHistory, "pomodoro", durations);
+    expect(synchronized).toMatchObject({ mode: "pomodoro", phase: "focus", status: "idle" });
+    expect(synchronized.history).toEqual(withHistory.history);
+  });
+
+  it("rejects inconsistent stored deadlines and modes", () => {
+    const valid = createTimerRuntime("pomodoro", durations);
+    expect(isTimerRuntimeState(valid)).toBe(true);
+    expect(isTimerRuntimeState({ ...valid, status: "running", deadline: null })).toBe(false);
+    expect(isTimerRuntimeState({ ...valid, phase: "timer" })).toBe(false);
+  });
+});