feat: phase 2 widgets — registry, fetchers, clock, config dialog

Backend: internal/widget registry (type metadata + Fetcher), Pi-hole
v5 / AdGuard / Immich fetchers, /api/widgets/types + /api/widgets/:id/data
with 30s TTL cache (failures cached too), kind+config on item create/patch.
Config secrets are never logged or echoed in errors.

Frontend: WidgetContent host maps config.type to a component, polls
/data every 30s for server-backed types; clock renders client-side.
Generic WidgetDialog builds its form from the registry's field list.
Widget tiles are sortable items in both renderers.

Generated with [Devin](https://devin.ai)

Authored By: TDvorak <[email protected]>
Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

apps/frontend/src/App.tsx

@@ -1,8 +1,9 @@
 import { useState } from "react";
-import { Moon, Plus, Settings, Sun } from "lucide-react";
+import { LayoutGrid, Moon, Plus, Settings, Sun } from "lucide-react";
 import { BoardProvider, useBoard } from "@/board/store";
 import { Board } from "@/board/Board";
 import { ServiceDialog } from "@/components/ServiceDialog";
+import { WidgetDialog } from "@/components/WidgetDialog";
 import { SettingsDialog } from "@/components/SettingsDialog";
 import { Button } from "@/components/ui/button";
 import type { Item } from "@/types";
@@ -19,8 +20,15 @@ function Shell() {
 	const board = useBoard();
 	const [settingsOpen, setSettingsOpen] = useState(false);
 	const [svcOpen, setSvcOpen] = useState(false);
+	const [wdgOpen, setWdgOpen] = useState(false);
 	const [editing, setEditing] = useState<Item | undefined>();
 
+	function openEditor(it: Item) {
+		setEditing(it);
+		if (it.kind === "widget") setWdgOpen(true);
+		else setSvcOpen(true);
+	}
+
 	return (
 		<div className="font-sans">
 			<header className="sticky top-0 z-10 flex items-center gap-3.5 border-b border-border bg-bg/80 px-7 py-3.5 backdrop-blur-md">
@@ -46,6 +54,13 @@ function Shell() {
 					>
 						{board.theme === "dark" ? <Moon size={15} strokeWidth={1.8} /> : <Sun size={15} strokeWidth={1.8} />}
 					</Button>
+					<Button
+						variant="outline" aria-label="Add widget"
+						onClick={() => { setEditing(undefined); setWdgOpen(true); }}
+					>
+						<LayoutGrid size={13} strokeWidth={2} />
+						Widget
+					</Button>
 					<Button onClick={() => { setEditing(undefined); setSvcOpen(true); }}>
 						<Plus size={13} strokeWidth={2.2} />
 						Add service
@@ -53,9 +68,10 @@ function Shell() {
 				</div>
 			</header>
 
-			<Board onEditItem={(it) => { setEditing(it); setSvcOpen(true); }} />
+			<Board onEditItem={openEditor} />
 
-			<ServiceDialog open={svcOpen} onOpenChange={setSvcOpen} item={editing} />
+			<ServiceDialog open={svcOpen} onOpenChange={setSvcOpen} item={editing?.kind === "service" ? editing : undefined} />
+			<WidgetDialog open={wdgOpen} onOpenChange={setWdgOpen} item={editing?.kind === "widget" ? editing : undefined} />
 			<SettingsDialog open={settingsOpen} onOpenChange={setSettingsOpen} />
 		</div>
 	);

apps/frontend/src/components/ServiceDialog.tsx

@@ -69,6 +69,7 @@ export function ServiceDialog({
 				}
 				const created = await board.addItem({
 					sectionId: sid,
+					kind: "service",
 					name: name.trim(),
 					icon,
 					urls: cleanUrls,

apps/frontend/src/components/WidgetDialog.tsx

@@ -0,0 +1,169 @@
+import { useEffect, useState } from "react";
+import { useBoard } from "@/board/store";
+import type { Item } from "@/types";
+import { Button } from "@/components/ui/button";
+import {
+	Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
+import type { components } from "@dash/api-client";
+
+type WidgetType = components["schemas"]["WidgetType"];
+
+// One generic dialog for every widget type — the registry's field list
+// drives the inputs, so a new integration needs no dialog code.
+export function WidgetDialog({
+	open,
+	onOpenChange,
+	item,
+}: {
+	open: boolean;
+	onOpenChange: (o: boolean) => void;
+	item?: Item | undefined;
+}) {
+	const board = useBoard();
+	const editing = Boolean(item);
+
+	const [types, setTypes] = useState<WidgetType[]>([]);
+	const [type, setType] = useState("");
+	const [name, setName] = useState("");
+	const [sectionId, setSectionId] = useState("");
+	const [values, setValues] = useState<Record<string, string>>({});
+	const [busy, setBusy] = useState(false);
+	const [err, setErr] = useState("");
+
+	useEffect(() => {
+		if (!open) return;
+		setErr("");
+		// SAFETY: raw fetch — the generated client types only cover typed endpoints we call through api.ts.
+		fetch("/api/widgets/types")
+			.then((r) => r.json() as Promise<WidgetType[]>)
+			.then(setTypes)
+			.catch(() => setTypes([]));
+
+		const cfg = item?.config ?? null;
+		setType(cfg && typeof cfg.type === "string" ? cfg.type : "");
+		setName(item?.name ?? "");
+		setSectionId(item?.sectionId ?? board.sections[0]?.id ?? "");
+		const init: Record<string, string> = {};
+		if (cfg) {
+			for (const [k, v] of Object.entries(cfg)) {
+				if (k !== "type" && typeof v === "string") init[k] = v;
+			}
+		}
+		setValues(init);
+	}, [open, item, board.sections]);
+
+	const meta = types.find((t) => t.type === type);
+
+	async function submit() {
+		if (!type) return setErr("Pick a widget type"), undefined;
+		if (!name.trim()) return setErr("Name is required"), undefined;
+		if (meta?.fields.some((f) => f.required && !values[f.key]?.trim())) {
+			return setErr("Fill in the required fields"), undefined;
+		}
+		setBusy(true);
+		try {
+			const config: NonNullable<Item["config"]> = { type };
+			for (const f of meta?.fields ?? []) {
+				const v = values[f.key]?.trim();
+				if (v) config[f.key] = v;
+			}
+			if (editing && item) {
+				await board.patchItem(item.id, { name: name.trim(), config });
+			} else {
+				let sid = sectionId;
+				if (!sid) {
+					const sec = await board.addSection("Widgets");
+					if (!sec) throw new Error("could not create section");
+					sid = sec.id;
+				}
+				await board.addItem({ sectionId: sid, kind: "widget", name: name.trim(), config, urls: [] });
+			}
+			onOpenChange(false);
+		} catch (e) {
+			setErr(e instanceof Error ? e.message : "save failed");
+		} finally {
+			setBusy(false);
+		}
+	}
+
+	return (
+		<Dialog open={open} onOpenChange={onOpenChange}>
+			<DialogContent>
+				<DialogHeader>
+					<DialogTitle>{editing ? "Edit widget" : "Add widget"}</DialogTitle>
+					<DialogDescription>
+						{editing ? "Update widget settings." : "Pick a type and point it at your service."}
+					</DialogDescription>
+				</DialogHeader>
+
+				<div className="flex flex-col gap-4">
+					<div className="grid grid-cols-[1fr_150px] gap-3">
+						<div className="flex flex-col gap-1.5">
+							<Label htmlFor="wdg-name">Name</Label>
+							<Input id="wdg-name" value={name} onChange={(e) => setName(e.target.value)} placeholder="Pi-hole" autoFocus />
+						</div>
+						{!editing && board.sections.length > 0 && (
+							<div className="flex flex-col gap-1.5">
+								<Label>Section</Label>
+								<Select value={sectionId} onValueChange={setSectionId}>
+									<SelectTrigger><SelectValue /></SelectTrigger>
+									<SelectContent>
+										{board.sections.map((s) => (
+											<SelectItem key={s.id} value={s.id}>{s.name}</SelectItem>
+										))}
+									</SelectContent>
+								</Select>
+							</div>
+						)}
+					</div>
+
+					<div className="flex flex-col gap-1.5">
+						<Label>Type</Label>
+						<Select value={type} onValueChange={setType}>
+							<SelectTrigger><SelectValue placeholder="Pick one…" /></SelectTrigger>
+							<SelectContent>
+								{types.map((t) => (
+									<SelectItem key={t.type} value={t.type}>{t.name}</SelectItem>
+								))}
+							</SelectContent>
+						</Select>
+						{meta?.description ? (
+							<p className="text-[11px] text-text-faint">{meta.description}</p>
+						) : null}
+					</div>
+
+					{meta?.fields.map((f) => (
+						<div key={f.key} className="flex flex-col gap-1.5">
+							<Label htmlFor={`wdg-${f.key}`}>
+								{f.label}{f.required ? "" : " (optional)"}
+							</Label>
+							<Input
+								id={`wdg-${f.key}`}
+								type={f.secret ? "password" : "text"}
+								value={values[f.key] ?? ""}
+								placeholder={f.placeholder}
+								onChange={(e) => setValues((v) => ({ ...v, [f.key]: e.target.value }))}
+								className="font-mono text-[12px]"
+							/>
+						</div>
+					))}
+
+					{err ? <p className="text-[12px] text-destructive">{err}</p> : null}
+				</div>
+
+				<DialogFooter className="items-center">
+					<Button type="button" variant="outline" onClick={() => onOpenChange(false)} disabled={busy}>
+						Cancel
+					</Button>
+					<Button type="button" onClick={() => void submit()} disabled={busy}>
+						{busy ? "Saving…" : editing ? "Save" : "Add widget"}
+					</Button>
+				</DialogFooter>
+			</DialogContent>
+		</Dialog>
+	);
+}

apps/frontend/src/renderers/bento/index.tsx

@@ -2,6 +2,7 @@ import { ChevronDown, GripVertical, Pencil, Trash2 } from "lucide-react";
 import { cn } from "@/lib/utils";
 import { useItemDnd, useSectionDnd } from "@/board/dnd";
 import { IconImg, ItemAnchor, StatusChip, hostOf } from "@/board/primitives";
+import { WidgetContent } from "@/widgets";
 import type {
 	BoardViewProps,
 	ItemViewProps,
@@ -108,8 +109,9 @@ function ItemView({ item, sectionId, status, onEdit }: ItemViewProps) {
 	);
 }
 
-// Widget tiles land in Phase 2; render a quiet placeholder tile meanwhile.
-function WidgetView({ item, sectionId }: ItemViewProps) {
+// Widget tile: full row on small screens, half row (span 3) on wide —
+// matching the mockup's wider widget cells.
+function WidgetView({ item, sectionId, onEdit }: ItemViewProps) {
 	const dnd = useItemDnd(sectionId, item.id);
 	return (
 		<div
@@ -118,14 +120,25 @@ function WidgetView({ item, sectionId }: ItemViewProps) {
 			{...dnd.attributes}
 			{...dnd.listeners}
 			className={cn(
-				"col-span-1 flex min-h-[70px] items-center rounded-[10px] border border-dashed border-border-strong px-[15px] py-[13px]",
-				"min-[620px]:col-span-2",
+				"group/tile relative col-span-2 flex min-h-[70px] cursor-grab items-center gap-3",
+				"rounded-[10px] border border-border bg-surface px-[15px] py-[13px]",
+				"transition-colors hover:border-border-strong hover:bg-surface-hover active:scale-[0.98]",
+				"min-[620px]:col-span-2 min-[900px]:col-span-3",
 				dnd.isDragging && "opacity-35",
 			)}
 		>
-			<span className="text-[11px] font-semibold uppercase tracking-[0.12em] text-text-faint">
-				{item.name}
-			</span>
+			<WidgetContent item={item} />
+			<button
+				type="button"
+				aria-label={`Edit ${item.name}`}
+				onClick={(e) => {
+					e.stopPropagation();
+					onEdit();
+				}}
+				className="absolute right-2 top-2 rounded p-1 text-text-faint opacity-0 transition-opacity hover:text-text group-hover/tile:opacity-100"
+			>
+				<Pencil size={11} />
+			</button>
 		</div>
 	);
 }

apps/frontend/src/renderers/cards/index.tsx

@@ -2,6 +2,7 @@ import { ChevronDown, GripVertical, Pencil, Trash2 } from "lucide-react";
 import { cn } from "@/lib/utils";
 import { useItemDnd, useSectionDnd } from "@/board/dnd";
 import { IconImg, ItemAnchor, StatusChip, hostOf } from "@/board/primitives";
+import { WidgetContent } from "@/widgets";
 import type {
 	BoardViewProps,
 	ItemViewProps,
@@ -103,7 +104,7 @@ function ItemView({ item, sectionId, status, onEdit }: ItemViewProps) {
 	);
 }
 
-function WidgetView({ item, sectionId }: ItemViewProps) {
+function WidgetView({ item, sectionId, onEdit }: ItemViewProps) {
 	const dnd = useItemDnd(sectionId, item.id);
 	return (
 		<div
@@ -112,13 +113,24 @@ function WidgetView({ item, sectionId }: ItemViewProps) {
 			{...dnd.attributes}
 			{...dnd.listeners}
 			className={cn(
-				"flex items-center rounded-[10px] border border-dashed border-border-strong bg-surface px-4 py-3",
+				"group/card relative col-span-2 flex cursor-grab items-center gap-3",
+				"rounded-[10px] border border-border bg-surface px-3.5 py-3",
+				"transition-colors hover:border-border-strong hover:bg-surface-hover active:scale-[0.98]",
 				dnd.isDragging && "opacity-40",
 			)}
 		>
-			<span className="text-[10.5px] font-semibold uppercase tracking-[0.12em] text-text-faint">
-				{item.name}
-			</span>
+			<WidgetContent item={item} />
+			<button
+				type="button"
+				aria-label={`Edit ${item.name}`}
+				onClick={(e) => {
+					e.stopPropagation();
+					onEdit();
+				}}
+				className="absolute -right-1 -top-1 rounded-full border border-border bg-popover p-1 text-text-faint opacity-0 transition-opacity hover:text-text group-hover/card:opacity-100"
+			>
+				<Pencil size={10} />
+			</button>
 		</div>
 	);
 }

apps/frontend/src/widgets/blocker.tsx

@@ -0,0 +1,43 @@
+import type { Item } from "@/types";
+import type { WidgetData } from "@/widgets/index";
+
+// Shared DNS-blocker layout: big block-rate, queries + blocked counts.
+// Pi-hole and AdGuard return the same fields from their fetchers.
+
+function num(d: WidgetData | undefined, k: string): number {
+	const v = d?.[k];
+	return typeof v === "number" ? v : 0;
+}
+
+const fmt = (n: number) =>
+	n >= 1_000_000 ? `${(n / 1_000_000).toFixed(1)}M` : n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n);
+
+function BlockerWidget({ item, data, error }: { item: Item; data: WidgetData | undefined; error: string | undefined }) {
+	if (error) {
+		return <span className="font-mono text-[11px] text-text-faint">{item.name} — {error}</span>;
+	}
+	const pct = num(data, "blockedPercent");
+	return (
+		<div className="flex min-w-0 items-center gap-4">
+			<div className="flex min-w-0 flex-col gap-0.5">
+				<span className="font-mono text-[22px] font-medium leading-none tracking-tight tabular-nums">
+					{data ? `${pct.toFixed(1)}%` : "…"}
+				</span>
+				<span className="text-[10.5px] uppercase tracking-[0.1em] text-text-faint">blocked</span>
+			</div>
+			<div className="ml-auto flex flex-col items-end gap-1 font-mono text-[10.5px] text-text-faint">
+				<span>{fmt(num(data, "queriesToday"))} queries</span>
+				<span>{fmt(num(data, "blockedToday"))} blocked</span>
+				{typeof data?.avgProcessMs === "number" && <span>{num(data, "avgProcessMs").toFixed(0)} ms avg</span>}
+			</div>
+		</div>
+	);
+}
+
+export function PiholeWidget(p: { item: Item; data: WidgetData | undefined; error: string | undefined }) {
+	return <BlockerWidget {...p} />;
+}
+
+export function AdguardWidget(p: { item: Item; data: WidgetData | undefined; error: string | undefined }) {
+	return <BlockerWidget {...p} />;
+}

apps/frontend/src/widgets/clock.tsx

@@ -0,0 +1,32 @@
+import { useEffect, useState } from "react";
+import type { Item } from "@/types";
+import { cfgStr } from "@/widgets/index";
+
+// Clock — fully client-side; ticks once a second.
+export function ClockWidget({ item }: { item: Item }) {
+	const tz = cfgStr(item, "timezone") || undefined;
+	const [now, setNow] = useState(() => new Date());
+
+	useEffect(() => {
+		const t = setInterval(() => setNow(new Date()), 1000);
+		return () => clearInterval(t);
+	}, []);
+
+	const time = new Intl.DateTimeFormat(undefined, {
+		hour: "2-digit", minute: "2-digit", second: "2-digit", hour12: false, timeZone: tz,
+	}).format(now);
+	const date = new Intl.DateTimeFormat(undefined, {
+		weekday: "short", month: "short", day: "numeric", timeZone: tz,
+	}).format(now);
+
+	return (
+		<div className="flex min-w-0 flex-col justify-center gap-0.5">
+			<span className="font-mono text-[22px] font-medium leading-none tracking-tight tabular-nums">
+				{time}
+			</span>
+			<span className="truncate text-[10.5px] uppercase tracking-[0.1em] text-text-faint">
+				{date}{tz ? ` · ${tz.split("/").pop()?.replace("_", " ")}` : ""}
+			</span>
+		</div>
+	);
+}

apps/frontend/src/widgets/immich.tsx

@@ -0,0 +1,35 @@
+import type { Item } from "@/types";
+import type { WidgetData } from "@/widgets/index";
+
+// Immich — photo/video counts and library footprint.
+
+function num(d: WidgetData | undefined, k: string): number {
+	const v = d?.[k];
+	return typeof v === "number" ? v : 0;
+}
+
+const fmtNum = (n: number) =>
+	n >= 1_000_000 ? `${(n / 1_000_000).toFixed(1)}M` : n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n);
+
+const fmtBytes = (b: number) =>
+	b >= 1 << 30 ? `${(b / (1 << 30)).toFixed(1)} GB` : `${(b / (1 << 20)).toFixed(0)} MB`;
+
+export function ImmichWidget({ item, data, error }: { item: Item; data: WidgetData | undefined; error: string | undefined }) {
+	if (error) {
+		return <span className="font-mono text-[11px] text-text-faint">{item.name} — {error}</span>;
+	}
+	return (
+		<div className="flex min-w-0 items-center gap-4">
+			<div className="flex min-w-0 flex-col gap-0.5">
+				<span className="font-mono text-[22px] font-medium leading-none tracking-tight tabular-nums">
+					{data ? fmtNum(num(data, "photos")) : "…"}
+				</span>
+				<span className="text-[10.5px] uppercase tracking-[0.1em] text-text-faint">photos</span>
+			</div>
+			<div className="ml-auto flex flex-col items-end gap-1 font-mono text-[10.5px] text-text-faint">
+				<span>{fmtNum(num(data, "videos"))} videos</span>
+				<span>{fmtBytes(num(data, "usageBytes"))}</span>
+			</div>
+		</div>
+	);
+}

apps/frontend/src/widgets/index.tsx

@@ -0,0 +1,99 @@
+import { useEffect, useState } from "react";
+import type { Item } from "@/types";
+import { ClockWidget } from "@/widgets/clock";
+import { PiholeWidget, AdguardWidget } from "@/widgets/blocker";
+import { ImmichWidget } from "@/widgets/immich";
+
+// WidgetHost seam: renderers own the tile chrome; this maps config.type to
+// the component that fills it. Adding a widget = one fetcher in Go + one
+// entry here.
+
+export type WidgetComponent = (p: { item: Item; data: WidgetData | undefined; error: string | undefined }) => React.ReactNode;
+
+export interface WidgetData {
+	[key: string]: string | number | boolean | undefined;
+}
+
+// Widget payloads are free-form per type; components read fields defensively.
+function isData(v: unknown): v is WidgetData {
+	return typeof v === "object" && v !== null;
+}
+
+interface WidgetRegistry {
+	[type: string]: { local?: boolean; view: WidgetComponent };
+}
+
+const registry: WidgetRegistry = {
+	clock: { local: true, view: ClockWidget },
+	pihole: { view: PiholeWidget },
+	adguard: { view: AdguardWidget },
+	immich: { view: ImmichWidget },
+};
+
+export function cfgStr(item: Item, key: string): string {
+	const cfg = item.config;
+	if (!cfg) return "";
+	const v = cfg[key];
+	return typeof v === "string" ? v : "";
+}
+
+export function cfgType(item: Item): string {
+	return cfgStr(item, "type");
+}
+
+/** Polls /api/widgets/:id/data every 30s for server-backed widgets. */
+export function useWidgetData(item: Item): { data: WidgetData | undefined; error: string | undefined } {
+	const type = cfgType(item);
+	const local = registry[type]?.local ?? false;
+	const [state, setState] = useState<{ data: WidgetData | undefined; error: string | undefined }>({
+		data: undefined, error: undefined,
+	});
+
+	useEffect(() => {
+		if (local || !type) return;
+		let dead = false;
+		let timer: ReturnType<typeof setTimeout>;
+
+		const tick = async () => {
+			try {
+				const res = await fetch(`/api/widgets/${item.id}/data`);
+				const body: unknown = await res.json();
+				if (dead) return;
+				if (!res.ok) {
+					let msg = "fetch failed";
+					if (typeof body === "object" && body !== null && "error" in body) {
+						msg = String(body.error);
+					}
+					setState((s) => ({ data: s.data, error: msg }));
+				} else {
+					let data: WidgetData = {};
+					if (typeof body === "object" && body !== null && "data" in body && isData(body.data)) {
+						data = body.data;
+					}
+					setState({ data, error: undefined });
+				}
+			} catch {
+				if (!dead) setState((s) => ({ data: s.data, error: "offline" }));
+			}
+			if (!dead) timer = setTimeout(tick, 30_000);
+		};
+		void tick();
+		return () => {
+			dead = true;
+			clearTimeout(timer);
+		};
+	}, [item.id, type, local]);
+
+	return state;
+}
+
+/** WidgetContent renders inside a renderer's tile chrome. */
+export function WidgetContent({ item }: { item: Item }) {
+	const { data, error } = useWidgetData(item);
+	const type = cfgType(item);
+	const entry = registry[type];
+	if (!entry) {
+		return <span className="text-[11px] uppercase tracking-[0.1em] text-text-faint">{item.name || "widget"}</span>;
+	}
+	return <>{entry.view({ item, data, error })}</>;
+}