From 9af1fa1d422ac8252d92c4a1e8b7c031fcba94a8 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Wed, 27 May 2026 23:52:47 +0800
Subject: [PATCH 01/18] refactor(web): polish gauge widget visuals
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- move 270° gap to the bottom (speedometer-style horseshoe)
- fill the card by enlarging the ring radius and dropping end-cap balls
- lock the visible card to a 1:1 aspect via container-size queries so it
  stays square inside non-square grid cells
- add internal padding between the ring and the card border
- move the server name into the bottom arc gap
---
 .../components/dashboard/dashboard-grid.tsx   |   2 -
 .../components/dashboard/widgets/gauge.tsx    | 153 ++++++++++--------
 ...2026-05-27-gauge-widget-redesign-design.md |   4 +-
 3 files changed, 87 insertions(+), 72 deletions(-)

diff --git a/apps/web/src/components/dashboard/dashboard-grid.tsx b/apps/web/src/components/dashboard/dashboard-grid.tsx
index efd545b6..391fc1fc 100644
--- a/apps/web/src/components/dashboard/dashboard-grid.tsx
+++ b/apps/web/src/components/dashboard/dashboard-grid.tsx
@@ -265,8 +265,6 @@ export function DashboardGrid({
           h: autoIdSet.has(item.i) ? item.h : Math.max(SCALE, Math.round(item.h / SCALE) * SCALE)
         }
         if (squareIdSet.has(item.i)) {
-          // Lock height to width (in fine units, h = w * SCALE) so the gauge
-          // stays a coarse-unit square no matter which dimension the user drags.
           base.h = base.w * SCALE
         }
         return base
diff --git a/apps/web/src/components/dashboard/widgets/gauge.tsx b/apps/web/src/components/dashboard/widgets/gauge.tsx
index e6282097..e0838c06 100644
--- a/apps/web/src/components/dashboard/widgets/gauge.tsx
+++ b/apps/web/src/components/dashboard/widgets/gauge.tsx
@@ -12,12 +12,14 @@ interface GaugeWidgetProps {
 // SVG geometry constants (viewBox is 100x100)
 const VIEWBOX = 100
 const CENTER = VIEWBOX / 2
-const RADIUS = 38
+// Radius pushes the ring close to the viewBox edge so the gauge fills the
+// card; clamped so the round linecap (STROKE/2 outward) still fits inside.
+const RADIUS = 44
 const STROKE = 8
-const BALL_R = 5.5
-const BALL_R_INNER = 2
-// 270° sweep, gap centered at top. Angles in degrees, clockwise from 12 o'clock.
-const START_ANGLE = 135
+// 270° sweep, gap centered at bottom. Angles in degrees, clockwise from 12 o'clock.
+// Start at 7:30 (225°), sweep clockwise past 9, 12, 3 to 4:30 (135°), leaving a
+// 90° gap centered at 6 o'clock — matches the reference horseshoe orientation.
+const START_ANGLE = 225
 const SWEEP = 270
 
 interface Gradient {
@@ -109,79 +111,94 @@ export function GaugeWidget({ config, servers }: GaugeWidgetProps) {
 
   const trackPathD = arcPath(CENTER, CENTER, RADIUS, START_ANGLE, trackEnd)
   const progressPathD = arcPath(CENTER, CENTER, RADIUS, START_ANGLE, progressEnd)
-  const startCap = polarToCartesian(CENTER, CENTER, RADIUS, START_ANGLE)
-  const endCap = polarToCartesian(CENTER, CENTER, RADIUS, progressEnd)
 
   const showProgress = value > 0
 
-  return (
-    <div className="@container/gauge relative flex h-full flex-col items-center justify-center overflow-hidden rounded-lg border bg-card p-3">
-      <svg
+  const mainText = (
+    <>
+      <Icon
         aria-hidden="true"
-        className="absolute inset-0 h-full w-full"
-        data-testid="gauge-svg"
-        viewBox={`0 0 ${VIEWBOX} ${VIEWBOX}`}
+        className="@[14rem]:h-4 @[20rem]:h-5 h-3.5 @[14rem]:w-4 @[20rem]:w-5 w-3.5"
+        style={{ color: gradient.start }}
+      />
+      <p
+        className="mt-1 truncate font-medium @[14rem]:text-sm text-xs"
+        data-testid="gauge-label"
+        style={{ color: gradient.start }}
+      >
+        {label}
+      </p>
+      <p
+        className="mt-1 font-bold @[14rem]:text-2xl @[20rem]:text-3xl @[26rem]:text-4xl text-foreground text-xl tabular-nums"
+        data-testid="gauge-value"
       >
-        <defs>
-          <linearGradient data-testid="gauge-gradient" id={gradientId} x1="0%" x2="100%" y1="0%" y2="100%">
-            <stop offset="0%" stopColor={gradient.start} />
-            <stop offset="100%" stopColor={gradient.end} />
-          </linearGradient>
-        </defs>
+        {value.toFixed(1)}%
+      </p>
+    </>
+  )
+
+  // Server name sits at the bottom of the card, inside the arc gap (the 90°
+  // opening centered at 6 o'clock). Anchored via absolute positioning so it
+  // doesn't shift the centered icon/label/value stack.
+  const subtitle = (
+    <p
+      className="absolute inset-x-3 bottom-[8%] z-10 truncate text-center text-muted-foreground text-xs"
+      data-testid="gauge-subtitle"
+    >
+      {server.name}
+    </p>
+  )
+
+  const svg = (
+    <svg
+      aria-hidden="true"
+      className="absolute inset-0 h-full w-full"
+      data-testid="gauge-svg"
+      viewBox={`0 0 ${VIEWBOX} ${VIEWBOX}`}
+    >
+      <defs>
+        <linearGradient data-testid="gauge-gradient" id={gradientId} x1="0%" x2="100%" y1="0%" y2="100%">
+          <stop offset="0%" stopColor={gradient.start} />
+          <stop offset="100%" stopColor={gradient.end} />
+        </linearGradient>
+      </defs>
+      <path
+        d={trackPathD}
+        data-testid="gauge-track"
+        fill="none"
+        stroke="var(--color-muted)"
+        strokeLinecap="round"
+        strokeOpacity={0.35}
+        strokeWidth={STROKE}
+      />
+      {showProgress && (
         <path
-          d={trackPathD}
-          data-testid="gauge-track"
+          d={progressPathD}
+          data-testid="gauge-progress"
           fill="none"
-          stroke="var(--color-muted)"
+          stroke={`url(#${gradientId})`}
           strokeLinecap="round"
-          strokeOpacity={0.35}
           strokeWidth={STROKE}
         />
-        {showProgress && (
-          <path
-            d={progressPathD}
-            data-testid="gauge-progress"
-            fill="none"
-            stroke={`url(#${gradientId})`}
-            strokeLinecap="round"
-            strokeWidth={STROKE}
-          />
-        )}
-        {showProgress && (
-          <g data-testid="gauge-endcaps">
-            <circle cx={startCap.x} cy={startCap.y} fill="white" r={BALL_R} />
-            <circle cx={startCap.x} cy={startCap.y} fill={gradient.start} r={BALL_R_INNER} />
-            <circle cx={endCap.x} cy={endCap.y} fill="white" r={BALL_R} />
-            <circle cx={endCap.x} cy={endCap.y} fill={gradient.end} r={BALL_R_INNER} />
-          </g>
-        )}
-      </svg>
-
-      <div className="relative z-10 flex flex-col items-center text-center">
-        <Icon
-          aria-hidden="true"
-          className="@[10rem]:h-4 @[14rem]:h-5 h-3.5 @[10rem]:w-4 @[14rem]:w-5 w-3.5"
-          style={{ color: gradient.start }}
-        />
-        <p
-          className="mt-1 truncate font-medium @[10rem]:text-sm text-xs"
-          data-testid="gauge-label"
-          style={{ color: gradient.start }}
-        >
-          {label}
-        </p>
-        <p
-          className="mt-1 font-bold @[10rem]:text-3xl @[14rem]:text-4xl text-2xl text-foreground tabular-nums"
-          data-testid="gauge-value"
-        >
-          {value.toFixed(1)}%
-        </p>
-        <p
-          className="mt-1 @[8rem]:block hidden max-w-[80%] truncate text-muted-foreground text-xs"
-          data-testid="gauge-subtitle"
-        >
-          {server.name}
-        </p>
+      )}
+    </svg>
+  )
+
+  // The grid cell is generally not square (12-col grid step ≠ row step), so we
+  // size the visible card to min(cell_w, cell_h) via container-size queries on
+  // the wrapper. The card itself is always aspect-square; the cell may have
+  // empty space on one side that's transparent.
+  return (
+    <div className="grid h-full w-full place-items-center" style={{ containerType: 'size' }}>
+      <div
+        className="@container/gauge relative aspect-square overflow-hidden rounded-lg border bg-card"
+        style={{ width: 'min(100cqi, 100cqb)', height: 'min(100cqi, 100cqb)' }}
+      >
+        <div className="absolute inset-3">{svg}</div>
+        <div className="absolute inset-0 z-10 flex min-w-0 flex-col items-center justify-center p-3 text-center">
+          {mainText}
+        </div>
+        {subtitle}
       </div>
     </div>
   )
diff --git a/docs/superpowers/specs/2026-05-27-gauge-widget-redesign-design.md b/docs/superpowers/specs/2026-05-27-gauge-widget-redesign-design.md
index f68bd018..3fcb4d75 100644
--- a/docs/superpowers/specs/2026-05-27-gauge-widget-redesign-design.md
+++ b/docs/superpowers/specs/2026-05-27-gauge-widget-redesign-design.md
@@ -57,7 +57,7 @@ Stack (centered, vertical):
 
 Ring:
 
-- Sweep **270°** with the gap centered at the top (start angle `135°`, end angle `45°` measured clockwise from 12 o'clock — equivalent to the reference image's gap orientation).
+- Sweep **270°** with the gap centered at the bottom (start angle `225°`, end angle `135°` measured clockwise from 12 o'clock — a speedometer-style horseshoe opening downward).
 - Two SVG `<path>` elements:
   - **Track**: full 270° sweep, `stroke=var(--color-muted)`, low opacity.
   - **Progress**: from start angle to `start + (value/max) * 270°`, `stroke=url(#gauge-gradient-{id})`.
@@ -137,7 +137,7 @@ Constants (in viewBox units, 100×100):
 - `STROKE = 8`
 - `BALL_R = 5.5`
 - `BALL_R_INNER = 2`
-- Sweep: `startAngle = 135°`, `endAngle = 45°` (clockwise, 270° total)
+- Sweep: `startAngle = 225°`, `endAngle = 135°` (clockwise, 270° total)
 
 The text stack (icon + label + value + subtitle) sits in a centered absolutely-positioned `<div>` inside the same flex column, layered above the SVG via `position: relative` on the wrapper. Text never lives inside the SVG — this lets Tailwind's responsive font sizing and `truncate` work as usual.
 

From 29f912e64f1fa4e2627c82cb761a24e5fc5e939d Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Wed, 27 May 2026 23:52:53 +0800
Subject: [PATCH 02/18] fix(web): harden metric-card config against missing
 metric

- guard metric-card render with a friendly empty state when the metric
  spec is missing (also blocks the records query so it stops looping)
- seed default 'cpu' metric in WidgetConfigDialog on save so a no-change
  submit persists a valid config
- show selected option label in ServerSelect/MetricSelect triggers via
  SelectValue children render function instead of raw value
---
 .../dashboard/widget-config-dialog.tsx          | 17 ++++++++++++++---
 .../dashboard/widgets/metric-card.tsx           | 13 ++++++++++++-
 apps/web/src/locales/en/dashboard.json          |  3 ++-
 apps/web/src/locales/zh/dashboard.json          |  3 ++-
 4 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/apps/web/src/components/dashboard/widget-config-dialog.tsx b/apps/web/src/components/dashboard/widget-config-dialog.tsx
index bad124ff..bc436f57 100644
--- a/apps/web/src/components/dashboard/widget-config-dialog.tsx
+++ b/apps/web/src/components/dashboard/widget-config-dialog.tsx
@@ -128,7 +128,9 @@ function ServerSelect({
         value={value}
       >
         <SelectTrigger className="w-full">
-          <SelectValue placeholder={placeholder} />
+          <SelectValue placeholder={placeholder}>
+            {(v: string | null) => servers.find((s) => s.id === v)?.name ?? placeholder}
+          </SelectValue>
         </SelectTrigger>
         <SelectContent>
           {servers.map((s) => (
@@ -160,7 +162,9 @@ function MetricSelect({
       <Label>{label}</Label>
       <Select items={metrics} onValueChange={(v) => v !== null && onChange(v)} value={value}>
         <SelectTrigger className="w-full">
-          <SelectValue placeholder={placeholder} />
+          <SelectValue placeholder={placeholder}>
+            {(v: string | null) => metrics.find((m) => m.value === v)?.label ?? placeholder}
+          </SelectValue>
         </SelectTrigger>
         <SelectContent>
           {metrics.map((m) => (
@@ -707,7 +711,14 @@ export function WidgetConfigDialog({
   const needsNoConfig = widgetType === 'service-status' || widgetType === 'server-map'
 
   const handleSubmit = () => {
-    onSubmit(title, JSON.stringify(config))
+    // Seed per-widget defaults that the form only shows but doesn't write,
+    // so a "save without changes" doesn't persist an invalid empty config
+    // (e.g. the metric-card form displays 'cpu' but only commits it on user change).
+    const normalized = { ...config }
+    if (widgetType === 'metric-card' && normalized.metric === undefined) {
+      normalized.metric = 'cpu'
+    }
+    onSubmit(title, JSON.stringify(normalized))
     onOpenChange(false)
   }
 
diff --git a/apps/web/src/components/dashboard/widgets/metric-card.tsx b/apps/web/src/components/dashboard/widgets/metric-card.tsx
index b4d74cba..cc176675 100644
--- a/apps/web/src/components/dashboard/widgets/metric-card.tsx
+++ b/apps/web/src/components/dashboard/widgets/metric-card.tsx
@@ -29,11 +29,22 @@ export function MetricCardWidget({ config, servers }: MetricCardWidgetProps) {
   const server = useMemo(() => servers.find((s) => s.id === config.server_id), [servers, config.server_id])
 
   const { data: records } = useServerRecords(config.server_id, HISTORY_HOURS, HISTORY_INTERVAL, {
-    enabled: Boolean(config.server_id) && Boolean(server)
+    enabled: Boolean(config.server_id) && Boolean(server) && Boolean(spec)
   })
 
   const series = useMetricSeries({ records, server, metric: config.metric })
 
+  if (!spec) {
+    return (
+      <div
+        className="flex h-full items-center justify-center rounded-xl border bg-card text-muted-foreground text-sm"
+        data-testid="metric-card-missing-metric"
+      >
+        {t('metricCard.unknownMetric')}
+      </div>
+    )
+  }
+
   if (!server) {
     return (
       <div
diff --git a/apps/web/src/locales/en/dashboard.json b/apps/web/src/locales/en/dashboard.json
index d218e5b3..930c6d57 100644
--- a/apps/web/src/locales/en/dashboard.json
+++ b/apps/web/src/locales/en/dashboard.json
@@ -246,6 +246,7 @@
     "past1h": "past 1h",
     "peak": "24H PEAK",
     "avg": "24H AVG",
-    "unknownServer": "Unknown server"
+    "unknownServer": "Unknown server",
+    "unknownMetric": "Metric not configured"
   }
 }
diff --git a/apps/web/src/locales/zh/dashboard.json b/apps/web/src/locales/zh/dashboard.json
index 86c85100..5417ac42 100644
--- a/apps/web/src/locales/zh/dashboard.json
+++ b/apps/web/src/locales/zh/dashboard.json
@@ -246,6 +246,7 @@
     "past1h": "过去 1 小时",
     "peak": "24H 峰值",
     "avg": "24H 均值",
-    "unknownServer": "未知服务器"
+    "unknownServer": "未知服务器",
+    "unknownMetric": "未配置指标"
   }
 }

From 2d9e85fb58e230ff7219b74ac8baa87cf7034475 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 00:18:06 +0800
Subject: [PATCH 03/18] feat(web): make square widget cells pixel-square in the
 grid

The 12-col grid step (~85px) and the fine row step (24px) are asymmetric, so
a square widget with `w_coarse === h_coarse` rendered as a tall rectangle.

Derive the rendered h from w via `visualSquareHFine = round(w * colStep /
fineRowStep)` so the cell ends up pixel-square in steady state. The persisted
`grid_h` still mirrors `grid_w` (square invariant); only the rendered fine h
differs.

To stop RGL from undoing the override:
- minH/maxH are derived too so the post-render clamp matches the override
- during an active resize, h tracks `w * SCALE` so react-resizable's cursor
  delta stays in sync; idle RGL echoes keep the pixel-square value via an
  interactionState ref check
---
 .../components/dashboard/dashboard-grid.tsx   | 50 ++++++++++++++++---
 1 file changed, 43 insertions(+), 7 deletions(-)

diff --git a/apps/web/src/components/dashboard/dashboard-grid.tsx b/apps/web/src/components/dashboard/dashboard-grid.tsx
index 391fc1fc..6a10d2c7 100644
--- a/apps/web/src/components/dashboard/dashboard-grid.tsx
+++ b/apps/web/src/components/dashboard/dashboard-grid.tsx
@@ -194,6 +194,23 @@ export function DashboardGrid({
     [widgets]
   )
 
+  // Square widgets persist as `w_coarse === h_coarse`, but coarse rows are
+  // taller than columns (96px vs ~85px), so the rendered cell is rectangular.
+  // Override the render height in fine units so the cell is pixel-square. The
+  // persisted coarse height is left untouched — only the rendered height
+  // changes, and a drag commit re-derives both from `w`.
+  const visualSquareHFine = useCallback(
+    (wCoarse: number): number => {
+      if (width <= 0) {
+        return wCoarse * SCALE
+      }
+      const colStepPx = (width + MARGIN[0]) / COLS
+      const fineRowStepPx = ROW_HEIGHT + MARGIN_Y
+      return Math.max(1, Math.round((wCoarse * colStepPx) / fineRowStepPx))
+    },
+    [width]
+  )
+
   // Persisted grid units are coarse (1 row == ROW_HEIGHT*SCALE px). The grid
   // itself runs at a SCALE-times finer row so content-sized widgets can hug
   // their content within ~ROW_HEIGHT px instead of a full coarse row. Scale the
@@ -219,15 +236,28 @@ export function DashboardGrid({
         item.resizeHandles = ['e']
       }
       if (squareIdSet.has(item.i)) {
-        // Square widgets resize on the corner only and snap to w === h on commit.
+        // Square widgets resize via the SE corner so the user can grow by
+        // dragging either edge of the cell. Idle h is the pixel-square value
+        // (visualSquareHFine); minH/maxH are also derived so RGL doesn't clamp
+        // h back to the un-overridden coarse-fine value.
         item.resizeHandles = ['se']
+        item.h = visualSquareHFine(item.w)
+        const minW = item.minW ?? 2
+        const maxW = item.maxW
+        item.minH = visualSquareHFine(minW)
+        item.maxH = maxW !== undefined ? visualSquareHFine(maxW) : undefined
       }
     }
     return deoverlapLayout(layout)
-  }, [widgets, autoUnits, squareIdSet])
+  }, [widgets, autoUnits, squareIdSet, visualSquareHFine])
 
   const [liveLayout, setLiveLayout] = useState<Layout>(baseLayout)
   const [interactionState, setInteractionState] = useState<InteractionState>('idle')
+  // Mirror interactionState into a ref so updateLiveLayout's callback (called
+  // on every RGL echo) can branch on "currently resizing" without forcing a
+  // re-bind every state transition.
+  const interactionStateRef = useRef(interactionState)
+  interactionStateRef.current = interactionState
 
   // While editing (or actively dragging/resizing), freeze the servers snapshot fed
   // to widgets. Otherwise every websocket tick swaps the servers array reference
@@ -265,7 +295,11 @@ export function DashboardGrid({
           h: autoIdSet.has(item.i) ? item.h : Math.max(SCALE, Math.round(item.h / SCALE) * SCALE)
         }
         if (squareIdSet.has(item.i)) {
-          base.h = base.w * SCALE
+          // While the user is actively resizing, h follows w in coarse units so
+          // react-resizable's cursor delta tracking stays consistent. On the
+          // idle echo (RGL re-emitting the rendered layout) keep the rendered
+          // pixel-square value so we don't undo the baseLayout override.
+          base.h = interactionStateRef.current === 'resizing' ? base.w * SCALE : visualSquareHFine(base.w)
         }
         return base
       })
@@ -274,7 +308,7 @@ export function DashboardGrid({
       // raw (overlapping) persisted positions over the de-overlapped layout.
       setLiveLayout(deoverlapLayout(snapped))
     },
-    [autoIdSet, squareIdSet]
+    [autoIdSet, squareIdSet, visualSquareHFine]
   )
 
   // Resync the rendered layout to the widgets-derived one the moment `widgets`
@@ -316,7 +350,7 @@ export function DashboardGrid({
           h: autoIdSet.has(item.i) ? item.h : Math.max(SCALE, Math.round(item.h / SCALE) * SCALE)
         }
         if (squareIdSet.has(item.i)) {
-          base.h = base.w * SCALE
+          base.h = visualSquareHFine(base.w)
         }
         return base
       })
@@ -325,14 +359,16 @@ export function DashboardGrid({
       const coarseLayout = resolved.map((item) => ({
         ...item,
         y: Math.round(item.y / SCALE),
-        h: Math.round(item.h / SCALE)
+        // Squares persist as h_coarse = w_coarse regardless of the visual
+        // fine-height override (which stays a pure render-time concern).
+        h: squareIdSet.has(item.i) ? item.w : Math.round(item.h / SCALE)
       }))
       const patch = layoutToPatch(coarseLayout, widgets)
       if (patch.length > 0) {
         onLayoutChange(patch)
       }
     },
-    [autoIdSet, squareIdSet, onLayoutChange, widgets]
+    [autoIdSet, squareIdSet, onLayoutChange, widgets, visualSquareHFine]
   )
 
   const sortedWidgets = useMemo(() => {

From fb22a2072c199507c471c4b28d74741d4b798eb5 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 00:18:10 +0800
Subject: [PATCH 04/18] style(web): de-emphasize the % suffix in the gauge
 value
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The percent sign is decoration, not data — render it smaller and dimmer so
the eye lands on the number first.
---
 apps/web/src/components/dashboard/widgets/gauge.tsx | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/apps/web/src/components/dashboard/widgets/gauge.tsx b/apps/web/src/components/dashboard/widgets/gauge.tsx
index e0838c06..8b24b5b6 100644
--- a/apps/web/src/components/dashboard/widgets/gauge.tsx
+++ b/apps/web/src/components/dashboard/widgets/gauge.tsx
@@ -132,7 +132,8 @@ export function GaugeWidget({ config, servers }: GaugeWidgetProps) {
         className="mt-1 font-bold @[14rem]:text-2xl @[20rem]:text-3xl @[26rem]:text-4xl text-foreground text-xl tabular-nums"
         data-testid="gauge-value"
       >
-        {value.toFixed(1)}%
+        {value.toFixed(1)}
+        <span className="ml-0.5 font-medium text-[0.6em] text-muted-foreground/70">%</span>
       </p>
     </>
   )

From 78e3cf695fe15c4fcb7aae4f24fd11c7b14a5c44 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 01:18:44 +0800
Subject: [PATCH 05/18] docs: spec for dashboard widget sizing strategy

Formalize the four sizing strategies (free, fixed, aspect-square,
content-height) into an explicit `sizing` field on each widget type,
backed by a per-strategy dispatcher. Replaces the scattered
SQUARE_TYPES / AUTO_HEIGHT_TYPES / inline isResizable derivation.
---
 ...dashboard-widget-sizing-strategy-design.md | 451 ++++++++++++++++++
 1 file changed, 451 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-05-28-dashboard-widget-sizing-strategy-design.md

diff --git a/docs/superpowers/specs/2026-05-28-dashboard-widget-sizing-strategy-design.md b/docs/superpowers/specs/2026-05-28-dashboard-widget-sizing-strategy-design.md
new file mode 100644
index 00000000..319d39c4
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-28-dashboard-widget-sizing-strategy-design.md
@@ -0,0 +1,451 @@
+---
+title: Dashboard Widget Sizing Strategy
+date: 2026-05-28
+status: Draft
+branch: lisbon
+related:
+  - apps/web/src/lib/widget-types.ts
+  - apps/web/src/components/dashboard/dashboard-grid.tsx
+  - apps/web/src/components/dashboard/dashboard-layout.ts
+---
+
+# Dashboard Widget Sizing Strategy
+
+## Goal
+
+Formalize how widgets behave in the dashboard grid (free resize, fixed size, aspect-locked square, content-driven height) into a single explicit `sizing` field on each widget type. Replace the scattered ad-hoc markers (`SQUARE_TYPES`, `AUTO_HEIGHT_TYPES`, `isResizable` derivation) with a typed dispatcher.
+
+The immediate trigger is the gauge widget — its aspect-locked sizing is implemented through a fragile stack of overrides spread across `dashboard-grid.tsx`, `dashboard-layout.ts`, and `gauge.tsx` that has broken resize behavior multiple times. Generalizing the model also addresses several smaller issues (missing `maxW` on `markdown`/`server-cards`, no documentation for "how to add a widget", no helper for internal UI adaptation).
+
+## Non-goals
+
+- Backend / database changes. `sizing` stays a client-side static config.
+- Migration scripts. Out-of-range widgets are clamped silently at render time.
+- iOS-style multi-tier widget UIs (small / medium / large with independent layouts). Container queries cover 80% of internal adaptation; the remaining 20% (aspect-locked widgets) are handled by the `aspect-square` strategy.
+- Changes to how the grid stores `grid_x / grid_y / grid_w / grid_h` per widget.
+
+---
+
+## 1. Strategy model
+
+Add a discriminated union to `widget-types.ts`:
+
+```ts
+export type SizingStrategy =
+  | { kind: 'free' }
+  | { kind: 'fixed' }
+  | { kind: 'aspect-square'; tiers: number[] }
+  | { kind: 'content-height' }
+
+export interface WidgetTypeDefinition {
+  // existing fields …
+  sizing: SizingStrategy
+}
+```
+
+The field is **required** on every widget type. The compiler refuses to accept a new widget that doesn't pick a strategy.
+
+### Strategy assignments
+
+| Widget          | Strategy                                              |
+| --------------- | ----------------------------------------------------- |
+| stat-number     | `{ kind: 'fixed' }`                                   |
+| metric-card     | `{ kind: 'free' }`                                    |
+| server-cards    | `{ kind: 'free' }` (maxW=12, maxH=12 added)           |
+| gauge           | `{ kind: 'aspect-square', tiers: [2, 3, 4, 5, 6] }`   |
+| line-chart      | `{ kind: 'free' }`                                    |
+| multi-line      | `{ kind: 'free' }`                                    |
+| top-n           | `{ kind: 'content-height' }`                          |
+| alert-list      | `{ kind: 'free' }`                                    |
+| service-status  | `{ kind: 'free' }`                                    |
+| traffic-bar     | `{ kind: 'free' }`                                    |
+| disk-io         | `{ kind: 'free' }`                                    |
+| server-map      | `{ kind: 'free' }`                                    |
+| markdown        | `{ kind: 'free' }` (maxW=8, maxH=8 added)             |
+| uptime-timeline | `{ kind: 'free' }`                                    |
+
+---
+
+## 2. Strategy dispatcher
+
+A new directory `apps/web/src/components/dashboard/sizing-strategies/` owns the per-strategy logic. `dashboard-grid.tsx` does not branch on widget type any more — it asks the dispatcher.
+
+### Directory layout
+
+```
+sizing-strategies/
+├── index.ts            // exports applyStrategy, snapOnRelease, types
+├── free.ts
+├── fixed.ts
+├── aspect-square.ts
+└── content-height.ts
+```
+
+### Dispatcher API
+
+```ts
+export type InteractionState = 'idle' | 'dragging' | 'resizing'
+
+export interface StrategyContext {
+  containerWidth: number
+  interactionState: InteractionState
+  autoMeasuredFineH?: number   // content-height: VisibilityGate measurement
+}
+
+export interface StrategyResult {
+  h: number                                // fine units
+  minH: number                             // fine units
+  maxH: number | undefined                 // fine units
+  resizeHandles?: ResizeHandleAxis[]       // undefined = RGL default
+  isResizable: boolean
+}
+
+export function applyStrategy(
+  item: LayoutItem,
+  strategy: SizingStrategy,
+  ctx: StrategyContext
+): StrategyResult
+
+export function snapOnRelease(
+  item: LayoutItem,
+  strategy: SizingStrategy,
+  ctx: StrategyContext
+): LayoutItem
+```
+
+`applyStrategy` is called in three places:
+
+- `baseLayout` (idle): `interactionState='idle'`
+- `updateLiveLayout` (during drag/resize): `interactionState='dragging' | 'resizing'`
+- `commitLayoutChange` (release): once with `'idle'` after `snapOnRelease`
+
+### `dashboard-grid.tsx` after refactor (sketch)
+
+```ts
+const baseLayout = useMemo(() => {
+  const layout = widgetsToLayout(widgets)
+  for (const item of layout) {
+    item.y *= SCALE
+    const strategy = getStrategy(item.widgetType)
+    const r = applyStrategy(item, strategy, {
+      containerWidth: width,
+      interactionState: 'idle',
+      autoMeasuredFineH: autoUnits[item.i]
+    })
+    item.h = r.h
+    item.minH = r.minH
+    item.maxH = r.maxH
+    if (r.resizeHandles) item.resizeHandles = r.resizeHandles
+    if (!r.isResizable) item.isResizable = false
+  }
+  return deoverlapLayout(layout)
+}, [widgets, autoUnits, width])
+```
+
+Same shape in `updateLiveLayout` and `commitLayoutChange`, with `interactionState` reflecting the actual phase via `interactionStateRef.current`.
+
+---
+
+## 3. `aspect-square` resize interaction
+
+This is the most subtle strategy and the one we've broken several times. Pin the details:
+
+### Drag flow
+
+1. **`onResizeStart`** → `setInteractionState('resizing')`. No special bookkeeping.
+
+2. **`onResize` (fires every cursor mousemove)** → RGL hands us the cursor-derived `newW` (coarse), `newH` (fine). For `aspect-square`:
+   - `targetCoarse = max(newW, ceil(newH / SCALE))` — take whichever axis the cursor drove further as the new edge.
+   - `base.w = clamp(targetCoarse, minW, maxW)`.
+   - `base.h = visualSquareHFine(base.w, ctx.containerWidth)` — pixel-square fine height for the new w.
+
+   Both `w` and `h` are derived from `targetCoarse`. RGL's react-resizable still owns the cursor → delta computation (it does not read our overridden `h` for that), so its internal state remains consistent across frames.
+
+3. **`onResizeStop`** → `commitLayoutChange` runs `snapOnRelease` first:
+   - `targetTier = nearestTier(base.w, strategy.tiers)`.
+   - Set `base.w = targetTier`, `base.h = visualSquareHFine(targetTier, ctx.containerWidth)`.
+   - Persist `grid_w = grid_h = targetTier` (coarse units; `visualSquareHFine` applies again at next idle render).
+
+### Idle h derivation (`visualSquareHFine`)
+
+The 12-col grid step (≈ container_width / 12) is wider than the fine row step (24px), so `h_coarse = w_coarse` renders rectangular. Override at render time:
+
+```ts
+function visualSquareHFine(wCoarse: number, containerWidth: number): number {
+  if (containerWidth <= 0) return wCoarse * SCALE  // pre-mount fallback
+  const colStepPx = (containerWidth + MARGIN_X) / COLS
+  const fineRowStepPx = ROW_HEIGHT + MARGIN_Y
+  return Math.max(1, Math.round((wCoarse * colStepPx) / fineRowStepPx))
+}
+```
+
+Move this helper into `sizing-strategies/aspect-square.ts`. It is not used by any other strategy.
+
+### `nearestTier` helper
+
+```ts
+function nearestTier(value: number, tiers: number[]): number {
+  return tiers.reduce((best, t) => (Math.abs(t - value) < Math.abs(best - value) ? t : best), tiers[0])
+}
+```
+
+Tie-break (e.g., value `3.5` with tiers `[3, 4]`): the first tier wins (`3`), which is the conservative choice (avoid accidental upgrades).
+
+### `aspect-square` `applyStrategy` cases
+
+| ctx.interactionState | h                                                            | minH                       | maxH                       | resizeHandles |
+| -------------------- | ------------------------------------------------------------ | -------------------------- | -------------------------- | ------------- |
+| `idle`               | `visualSquareHFine(item.w, ctx.width)`                       | `visualSquareHFine(minW)`  | `visualSquareHFine(maxW)`  | `['se']`      |
+| `resizing`           | `visualSquareHFine(base.w, ctx.width)` (after `w` is updated per the drag flow) | same as idle               | same as idle               | `['se']`      |
+| `dragging`           | same as idle (resize and drag are exclusive)                 | same as idle               | same as idle               | `['se']`      |
+
+### Edge cases
+
+- **MaxW boundary**: cursor keeps moving but `targetCoarse` is clamped to `maxW`. Cell stops at the maxW × maxW visual.
+- **Drag toward top-left**: RGL gives non-positive newW/newH. `targetCoarse` is computed as `max(...)`; if both axes shrink, it falls below `minW` and is clamped up to `minW`. Cell can't shrink below minW × minW.
+- **`preventCollision` blocks growth**: RGL refuses the new `newW`, so the layout that reaches `onResize` already has the blocked `w`. `targetCoarse` reflects that. The cell stops growing on the blocked side; the user can still grow further only if the other axis is also unblocked (because `targetCoarse` uses the larger of the two).
+- **Container width changes mid-render**: `visualSquareHFine` recomputes via the React tree. Cell visually scales with the container. `grid_w` does not change.
+
+---
+
+## 4. `content-height` strategy
+
+Behaves exactly like today's `AUTO_HEIGHT_TYPES`:
+
+```ts
+export function applyContentHeight(item, ctx): StrategyResult {
+  const measured = ctx.autoMeasuredFineH
+  if (measured !== undefined) {
+    return {
+      h: measured,
+      minH: measured,
+      maxH: measured,
+      resizeHandles: ['e'],
+      isResizable: true
+    }
+  }
+  const h = item.h * SCALE
+  return {
+    h,
+    minH: h,
+    maxH: h,
+    resizeHandles: ['e'],
+    isResizable: true
+  }
+}
+```
+
+`handleMeasure` (VisibilityGate callback) keeps writing into `autoUnits`. The strategy reads from `ctx.autoMeasuredFineH`.
+
+---
+
+## 5. `fixed` strategy
+
+```ts
+export function applyFixed(item, ctx): StrategyResult {
+  const h = item.h * SCALE
+  return { h, minH: h, maxH: h, resizeHandles: [], isResizable: false }
+}
+```
+
+Replaces the `if (minW === maxW && minH === maxH) isResizable = false` block in `dashboard-layout.ts`. `stat-number` becomes the only `fixed` widget today.
+
+---
+
+## 6. `free` strategy
+
+```ts
+export function applyFree(item, ctx): StrategyResult {
+  const minH = (item.minH ?? 1) * SCALE
+  const maxH = item.maxH !== undefined ? item.maxH * SCALE : undefined
+  return {
+    h: item.h * SCALE,
+    minH,
+    maxH,
+    resizeHandles: undefined,   // RGL default (all 8 corners/edges)
+    isResizable: true
+  }
+}
+```
+
+This is the no-op baseline. Most widgets use it.
+
+---
+
+## 7. `widgetsToLayout` clamp pass
+
+`dashboard-layout.ts` already clamps `grid_w` and `grid_h` to `[minW, maxW]` and `[minH, maxH]`. Extend it for `aspect-square`:
+
+```ts
+if (strategy.kind === 'aspect-square') {
+  const tier = nearestTier(Math.max(w, h), strategy.tiers)
+  w = h = tier
+}
+```
+
+Result: any historical widget with `grid_w !== grid_h` (or with a `grid_w` not in the tiers list) is silently corrected on first render. Persistence happens lazily on the next drag/resize, so no upfront migration is needed.
+
+---
+
+## 8. `widget-types.ts` changes
+
+Add bounds to the two unbounded widgets:
+
+```diff
+- { id: 'markdown', minW: 2, minH: 2 },
++ { id: 'markdown', minW: 2, minH: 2, maxW: 8, maxH: 8, sizing: { kind: 'free' } },
+
+- { id: 'server-cards', defaultW: 12, defaultH: 6, minW: 4, minH: 3 },
++ { id: 'server-cards', defaultW: 12, defaultH: 6, minW: 4, minH: 3, maxW: 12, maxH: 12, sizing: { kind: 'free' } },
+```
+
+Add `sizing` to every entry.
+
+---
+
+## 9. Deletions
+
+The refactor removes:
+
+- `SQUARE_TYPES` constant in `dashboard-grid.tsx`
+- `AUTO_HEIGHT_TYPES` constant in `dashboard-grid.tsx`
+- `squareIdSet` and `autoIdSet` memos
+- The inline `visualSquareHFine` and its 3-place override sites (moved into `sizing-strategies/aspect-square.ts`)
+- The `if (minW === maxW && minH === maxH) item.isResizable = false` block in `dashboard-layout.ts`
+
+`interactionStateRef` stays — multiple strategies use it.
+
+---
+
+## 10. Internal UI adaptation (P3)
+
+Most widgets already adapt via CSS container queries (`@container/foo`). This stays the default approach.
+
+For the rare case where JS-driven layout switching is needed (e.g., a chart wanting to hide its legend below 200px), add a small hook:
+
+```ts
+// apps/web/src/hooks/use-widget-size.ts
+export type SizeBucket = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+
+export interface WidgetSize {
+  width: number
+  height: number
+  bucket: SizeBucket
+}
+
+export function useWidgetSize(
+  ref: RefObject<HTMLElement>,
+  buckets?: Record<SizeBucket, number>
+): WidgetSize
+```
+
+Default bucket thresholds: `xs <160px, sm <240px, md <360px, lg <480px, xl ≥480px` (in widget width). Override via the `buckets` arg.
+
+The hook is **opt-in**. No existing widget is migrated. JSDoc explains "use container queries first, this hook only when CSS isn't enough".
+
+---
+
+## 11. Documentation (P2)
+
+New file `docs/dashboard-widget-checklist.md` (project doc, not a spec):
+
+````markdown
+# Adding a New Dashboard Widget
+
+## Required
+1. `widget-types.ts` — `WidgetTypeDefinition` entry with `sizing` set
+2. `widget-renderer.tsx` — add the switch case
+3. `widget-picker` — icon + i18n label
+4. `widget-config-dialog.tsx` — config form (if any)
+5. `locales/{en,zh}/dashboard.json` — i18n strings
+
+## Optional
+- Widget component: `apps/web/src/components/dashboard/widgets/<name>.tsx`
+- Vitest test: `apps/web/src/components/dashboard/widgets/<name>.test.tsx`
+
+## Picking a `sizing` strategy
+- Most widgets → `{ kind: 'free' }`
+- Single-value, one viable size → `{ kind: 'fixed' }`
+- Radial / gauge / aspect-locked → `{ kind: 'aspect-square', tiers: [...] }`
+- List / table with content-driven height → `{ kind: 'content-height' }`
+````
+
+---
+
+## 12. Testing
+
+### Unit tests (vitest)
+
+- `sizing-strategies/aspect-square.test.ts`
+  - drag mid-flight: `edge_fine = max(newW * SCALE, newH)`
+  - `snapOnRelease`: `base.w` snaps to nearest tier in tiers list
+  - clamps to `maxW` when cursor goes past
+  - clamps to `minW` when cursor goes negative
+  - persisted `grid_w === grid_h === tier`
+
+- `sizing-strategies/content-height.test.ts`
+  - `autoMeasuredFineH` takes priority over `item.h * SCALE`
+  - `resizeHandles === ['e']`
+  - `minH === maxH === h`
+
+- `sizing-strategies/fixed.test.ts`
+  - `isResizable === false`
+  - `resizeHandles === []`
+
+- `dashboard-layout.test.ts` (new)
+  - `widgetsToLayout` clamps `grid_w` past `maxW` silently
+  - `widgetsToLayout` snaps `aspect-square` widget with `grid_w !== grid_h` to the nearest tier
+
+### Manual verification
+
+New file `tests/manual/dashboard-widget-sizing.md`:
+
+- Gauge resize: drag SE from 2×2 to 6×6, releases snap to tier
+- Gauge resize: drag diagonally, cell stays square throughout
+- Gauge: window resize scales cells, persisted size unchanged
+- Top-N: cell height tracks content, only horizontal handle visible
+- Stat-number: not resizable, no handles
+- Markdown: cannot drag past width = 8 cols
+- Server-cards: cannot drag past width = 12 cols
+
+---
+
+## 13. Risk assessment
+
+| Risk                                                            | Mitigation                                                                                   |
+| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Existing gauge instances change visual size on first render     | Silent clamp + snap. No data loss. Users see a more-square cell — visual improvement, not loss. |
+| Refactor touches the dashboard-grid core flow                   | `sizing-strategies/` is independent and unit-tested. `dashboard-grid` becomes a thin caller. |
+| Adding `maxW` to `markdown` / `server-cards` shrinks rare wides | Clamp values (8 / 12) cover the practical range. The few that exceed are clamped once.       |
+| TS discriminated union landing partially                        | `sizing` is required on `WidgetTypeDefinition`. Compile-time enforced.                       |
+
+---
+
+## 14. Out of scope (deliberate)
+
+- iOS-style multi-tier widget UIs (separate small/medium/large layouts)
+- Backend-side sizing override per widget instance
+- Per-instance aspect-ratio override (e.g., a "2:1" gauge variant)
+- Drag-time mid-snap (snap only happens on release)
+- Animation on snap-to-tier (instant)
+
+Each of these can ship later as an additional strategy or extension without breaking the model.
+
+---
+
+## 15. File diff summary
+
+| File                                                            | Change                                                                |
+| --------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `apps/web/src/lib/widget-types.ts`                              | Add `SizingStrategy` type and `sizing` field; bound markdown/server-cards |
+| `apps/web/src/components/dashboard/sizing-strategies/`          | **New** directory: 4 strategy files + `index.ts`                      |
+| `apps/web/src/components/dashboard/dashboard-grid.tsx`          | Delete `SQUARE_TYPES`/`AUTO_HEIGHT_TYPES`/`visualSquareHFine`; call `applyStrategy` |
+| `apps/web/src/components/dashboard/dashboard-layout.ts`         | Delete inline `isResizable` check; add `aspect-square` clamp pass     |
+| `apps/web/src/hooks/use-widget-size.ts`                         | **New** opt-in hook                                                   |
+| `apps/web/src/components/dashboard/widgets/gauge.tsx`           | No code change (strategy moves out of gauge.tsx and into shared dispatcher) |
+| `apps/web/src/components/dashboard/sizing-strategies/*.test.ts` | **New** vitest coverage                                               |
+| `apps/web/src/components/dashboard/dashboard-layout.test.ts`    | **New** vitest coverage for clamp paths                               |
+| `docs/dashboard-widget-checklist.md`                            | **New** contributor checklist                                         |
+| `tests/manual/dashboard-widget-sizing.md`                       | **New** manual verification checklist                                 |
+
+No backend changes. No DB migrations. No env vars.

From 193ed37df0e339b3c2724ec3b848fdf07113311c Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 01:39:53 +0800
Subject: [PATCH 06/18] docs: revise widget sizing spec for two-layer model

Address review feedback:

- Fix react-grid-layout/core subpath import for aspectRatio and
  LayoutConstraint (root index does not re-export them).
- Split the design into Layer A (render-time normalizeRenderItem in
  baseLayout) and Layer B (resize-time LayoutConstraint via RGL's
  applySizeConstraints pipeline). RGL does not run constraints on idle
  layout sync, so aspect-square / content-height idle h must be set by
  baseLayout, not by constraints alone.
- snapOnRelease now returns a coarse-unit SnapPatch with an explicit
  applyCoarsePatch helper, ending the fine/coarse mix that broke the
  previous draft.
- updateLiveLayout keeps the existing SCALE-multiple h snap for free /
  fixed widgets to prevent resize jitter; aspect-square and
  content-height own their fine h via constraints / measurement.
---
 ...dashboard-widget-sizing-strategy-design.md | 602 ++++++++++--------
 1 file changed, 339 insertions(+), 263 deletions(-)

diff --git a/docs/superpowers/specs/2026-05-28-dashboard-widget-sizing-strategy-design.md b/docs/superpowers/specs/2026-05-28-dashboard-widget-sizing-strategy-design.md
index 319d39c4..9b1bdf3d 100644
--- a/docs/superpowers/specs/2026-05-28-dashboard-widget-sizing-strategy-design.md
+++ b/docs/superpowers/specs/2026-05-28-dashboard-widget-sizing-strategy-design.md
@@ -7,22 +7,29 @@ related:
   - apps/web/src/lib/widget-types.ts
   - apps/web/src/components/dashboard/dashboard-grid.tsx
   - apps/web/src/components/dashboard/dashboard-layout.ts
+  - node_modules/react-grid-layout/dist/core.d.ts (LayoutConstraint API, subpath import)
 ---
 
 # Dashboard Widget Sizing Strategy
 
 ## Goal
 
-Formalize how widgets behave in the dashboard grid (free resize, fixed size, aspect-locked square, content-driven height) into a single explicit `sizing` field on each widget type. Replace the scattered ad-hoc markers (`SQUARE_TYPES`, `AUTO_HEIGHT_TYPES`, `isResizable` derivation) with a typed dispatcher.
+Formalize how widgets behave in the dashboard grid (free resize, fixed size, aspect-locked square, content-driven height) into a single explicit `sizing` field on each widget type. Replace the scattered ad-hoc markers (`SQUARE_TYPES`, `AUTO_HEIGHT_TYPES`, hand-rolled `visualSquareHFine` inlined in three places, `interactionStateRef` branching, post-hoc layout overrides in `updateLiveLayout` / `commitLayoutChange`) with a two-layer model:
 
-The immediate trigger is the gauge widget — its aspect-locked sizing is implemented through a fragile stack of overrides spread across `dashboard-grid.tsx`, `dashboard-layout.ts`, and `gauge.tsx` that has broken resize behavior multiple times. Generalizing the model also addresses several smaller issues (missing `maxW` on `markdown`/`server-cards`, no documentation for "how to add a widget", no helper for internal UI adaptation).
+- **Render-time normalization** (`normalizeRenderItem`) runs in `baseLayout` to set each item's fine-unit h / minH / maxH at idle.
+- **Resize-time enforcement** uses RGL v2's `LayoutConstraint` API to keep the cell consistent during drag (no override race with react-resizable).
+
+The immediate trigger is the gauge widget — its aspect-locked sizing currently fights RGL's resize pipeline because we manipulate h *after* `onResize` fires. The new model lets RGL own the resize math via `aspectRatio(1)`, and we own the idle math via `normalizeRenderItem`, with both layers producing the same pixel-square fine h.
+
+Generalizing the model also addresses smaller issues: scattered strategy markers across three files; no documentation for "how to add a widget"; no compile-time enforcement that new widgets pick a strategy.
 
 ## Non-goals
 
 - Backend / database changes. `sizing` stays a client-side static config.
-- Migration scripts. Out-of-range widgets are clamped silently at render time.
-- iOS-style multi-tier widget UIs (small / medium / large with independent layouts). Container queries cover 80% of internal adaptation; the remaining 20% (aspect-locked widgets) are handled by the `aspect-square` strategy.
-- Changes to how the grid stores `grid_x / grid_y / grid_w / grid_h` per widget.
+- Migration scripts. Out-of-range widgets are clamped silently at render time by the existing `Math.max/Math.min` calls in `widgetsToLayout`.
+- iOS-style multi-tier widget UIs (independent small/medium/large layouts). Container queries cover 80% of internal adaptation; aspect-locked widgets handle the remaining 20% via `aspect-square`.
+- Backwards-incompatible bounds changes (e.g., capping markdown width). Existing `minW/maxW/minH/maxH` on each widget definition stay as-is.
+- A `useWidgetSize` hook for JS-driven internal layout switching. CSS container queries are the chosen pattern; revisit when a real widget needs more.
 
 ---
 
@@ -51,7 +58,7 @@ The field is **required** on every widget type. The compiler refuses to accept a
 | --------------- | ----------------------------------------------------- |
 | stat-number     | `{ kind: 'fixed' }`                                   |
 | metric-card     | `{ kind: 'free' }`                                    |
-| server-cards    | `{ kind: 'free' }` (maxW=12, maxH=12 added)           |
+| server-cards    | `{ kind: 'free' }`                                    |
 | gauge           | `{ kind: 'aspect-square', tiers: [2, 3, 4, 5, 6] }`   |
 | line-chart      | `{ kind: 'free' }`                                    |
 | multi-line      | `{ kind: 'free' }`                                    |
@@ -61,299 +68,404 @@ The field is **required** on every widget type. The compiler refuses to accept a
 | traffic-bar     | `{ kind: 'free' }`                                    |
 | disk-io         | `{ kind: 'free' }`                                    |
 | server-map      | `{ kind: 'free' }`                                    |
-| markdown        | `{ kind: 'free' }` (maxW=8, maxH=8 added)             |
+| markdown        | `{ kind: 'free' }` (existing bounds unchanged)        |
 | uptime-timeline | `{ kind: 'free' }`                                    |
 
----
-
-## 2. Strategy dispatcher
+The `tiers` array for `aspect-square` lists the legal coarse-grid sizes (w × w). For gauge: `[2, 3, 4, 5, 6]` — every integer between minW (2) and maxW (6).
 
-A new directory `apps/web/src/components/dashboard/sizing-strategies/` owns the per-strategy logic. `dashboard-grid.tsx` does not branch on widget type any more — it asks the dispatcher.
+---
 
-### Directory layout
+## 2. Two layers, two unit contracts
 
-```
-sizing-strategies/
-├── index.ts            // exports applyStrategy, snapOnRelease, types
-├── free.ts
-├── fixed.ts
-├── aspect-square.ts
-└── content-height.ts
-```
+This was the source of bugs in the previous draft. Pin both layers down:
 
-### Dispatcher API
+### Layer A: render-time normalization (`normalizeRenderItem`)
 
 ```ts
-export type InteractionState = 'idle' | 'dragging' | 'resizing'
+// sizing-strategies/normalize.ts
+import { SCALE, COLS, MARGIN, ROW_HEIGHT, MARGIN_Y } from '@/components/dashboard/grid-constants'
+import type { LayoutItem } from 'react-grid-layout'
 
-export interface StrategyContext {
+export interface NormalizeContext {
   containerWidth: number
-  interactionState: InteractionState
-  autoMeasuredFineH?: number   // content-height: VisibilityGate measurement
-}
-
-export interface StrategyResult {
-  h: number                                // fine units
-  minH: number                             // fine units
-  maxH: number | undefined                 // fine units
-  resizeHandles?: ResizeHandleAxis[]       // undefined = RGL default
-  isResizable: boolean
+  autoMeasuredFineH?: number   // set per-item by AutoHeightItem / ResizeObserver
 }
 
-export function applyStrategy(
+// Operates on a LayoutItem whose h is already in FINE units (after baseLayout's h *= SCALE).
+// Returns a new item with strategy-specific h / minH / maxH applied.
+export function normalizeRenderItem(
   item: LayoutItem,
   strategy: SizingStrategy,
-  ctx: StrategyContext
-): StrategyResult
+  ctx: NormalizeContext
+): LayoutItem {
+  switch (strategy.kind) {
+    case 'aspect-square': {
+      const h = pixelSquareFineH(item.w, ctx.containerWidth)
+      const minH = pixelSquareFineH(item.minW ?? 2, ctx.containerWidth)
+      const maxH = item.maxW !== undefined ? pixelSquareFineH(item.maxW, ctx.containerWidth) : undefined
+      return { ...item, h, minH, maxH }
+    }
+    case 'content-height': {
+      const measured = ctx.autoMeasuredFineH
+      if (measured !== undefined) {
+        return { ...item, h: measured, minH: measured, maxH: measured }
+      }
+      return item
+    }
+    case 'fixed':
+    case 'free':
+      return item
+  }
+}
 
-export function snapOnRelease(
-  item: LayoutItem,
-  strategy: SizingStrategy,
-  ctx: StrategyContext
-): LayoutItem
+// Same formula RGL's aspectRatio(1) uses internally — see chunk-XYPIYYYQ.mjs:61.
+function pixelSquareFineH(wCoarse: number, containerWidth: number): number {
+  if (containerWidth <= 0) return wCoarse * SCALE
+  const colStepPx = (containerWidth + MARGIN[0]) / COLS
+  const fineRowStepPx = ROW_HEIGHT + MARGIN_Y
+  return Math.max(1, Math.round((wCoarse * colStepPx) / fineRowStepPx))
+}
 ```
 
-`applyStrategy` is called in three places:
+This is called once per item in `baseLayout`, after the existing `h *= SCALE` and `minH *= SCALE` / `maxH *= SCALE` conversion. The function operates **purely in fine units** for h, minH, maxH.
 
-- `baseLayout` (idle): `interactionState='idle'`
-- `updateLiveLayout` (during drag/resize): `interactionState='dragging' | 'resizing'`
-- `commitLayoutChange` (release): once with `'idle'` after `snapOnRelease`
-
-### `dashboard-grid.tsx` after refactor (sketch)
+### Layer B: resize-time constraints (`applyStrategy`)
 
 ```ts
-const baseLayout = useMemo(() => {
-  const layout = widgetsToLayout(widgets)
-  for (const item of layout) {
-    item.y *= SCALE
-    const strategy = getStrategy(item.widgetType)
-    const r = applyStrategy(item, strategy, {
-      containerWidth: width,
-      interactionState: 'idle',
-      autoMeasuredFineH: autoUnits[item.i]
-    })
-    item.h = r.h
-    item.minH = r.minH
-    item.maxH = r.maxH
-    if (r.resizeHandles) item.resizeHandles = r.resizeHandles
-    if (!r.isResizable) item.isResizable = false
-  }
-  return deoverlapLayout(layout)
-}, [widgets, autoUnits, width])
-```
-
-Same shape in `updateLiveLayout` and `commitLayoutChange`, with `interactionState` reflecting the actual phase via `interactionStateRef.current`.
+// sizing-strategies/index.ts
+import { aspectRatio } from 'react-grid-layout/core'
+import type { LayoutConstraint, ResizeHandleAxis } from 'react-grid-layout/core'
+
+export interface StrategyDescriptor {
+  // Attached to LayoutItem.constraints. Applied by RGL inside applySizeConstraints
+  // during the resize pipeline. NOT applied at layout sync / idle render.
+  constraints: LayoutConstraint[]
+  resizeHandles?: ResizeHandleAxis[]
+  isResizable: boolean
+}
 
----
+export function applyStrategy(strategy: SizingStrategy, measuredFineH?: number): StrategyDescriptor {
+  switch (strategy.kind) {
+    case 'free':
+      return { constraints: [], resizeHandles: undefined, isResizable: true }
+    case 'fixed':
+      return { constraints: [], resizeHandles: [], isResizable: false }
+    case 'aspect-square':
+      return { constraints: [aspectRatio(1)], resizeHandles: ['se'], isResizable: true }
+    case 'content-height':
+      return {
+        constraints: measuredFineH !== undefined ? [lockHeight(measuredFineH)] : [],
+        resizeHandles: ['e'],
+        isResizable: true
+      }
+  }
+}
 
-## 3. `aspect-square` resize interaction
+function lockHeight(fineH: number): LayoutConstraint {
+  return {
+    name: `lockHeight(${fineH})`,
+    constrainSize(_item, w) {
+      return { w, h: fineH }
+    }
+  }
+}
+```
 
-This is the most subtle strategy and the one we've broken several times. Pin the details:
+The `constraints` array is attached to each `LayoutItem` in `baseLayout`. RGL invokes them inside `applySizeConstraints` during resize (verified in `react-grid-layout@2.2.2/dist/chunk-XM2M6TC6.mjs:356`).
 
-### Drag flow
+**Important**: RGL does not apply constraints at layout sync time (`synchronizeLayoutWithChildren` at `chunk-XM2M6TC6.mjs:550` just clones / corrects bounds / compacts). That's why Layer A is necessary — without `normalizeRenderItem`, gauge would render with `h = w * SCALE` (rectangular) at mount and remain rectangular until the user resizes it. The two layers split idle h (Layer A) from drag-time h (Layer B), each in its proper place.
 
-1. **`onResizeStart`** → `setInteractionState('resizing')`. No special bookkeeping.
+### Unit contract per pipeline stage
 
-2. **`onResize` (fires every cursor mousemove)** → RGL hands us the cursor-derived `newW` (coarse), `newH` (fine). For `aspect-square`:
-   - `targetCoarse = max(newW, ceil(newH / SCALE))` — take whichever axis the cursor drove further as the new edge.
-   - `base.w = clamp(targetCoarse, minW, maxW)`.
-   - `base.h = visualSquareHFine(base.w, ctx.containerWidth)` — pixel-square fine height for the new w.
+| Stage                                  | w               | h               | Owner                                  |
+| -------------------------------------- | --------------- | --------------- | -------------------------------------- |
+| Persisted (`DashboardWidget`)          | coarse          | coarse          | DB / API                               |
+| `widgetsToLayout` output               | coarse          | coarse          | `dashboard-layout.ts`                  |
+| `baseLayout` after `h *= SCALE`        | coarse          | **fine** (raw)  | `dashboard-grid.tsx`                   |
+| `baseLayout` after `normalizeRenderItem` | coarse        | **fine** (strategy-normalized) | Layer A         |
+| `liveLayout` / RGL `layout` prop       | coarse          | fine            | renders                                |
+| RGL `onResize` callback                | coarse          | fine (constrained by Layer B) | RGL pipeline       |
+| `updateLiveLayout` after y/h snap      | coarse          | fine            | `dashboard-grid.tsx`                   |
+| `snapOnRelease` output                 | coarse          | **coarse** (persistence patch) | Layer A's snap helper |
+| Persisted again                        | coarse          | coarse          | back to DB                             |
 
-   Both `w` and `h` are derived from `targetCoarse`. RGL's react-resizable still owns the cursor → delta computation (it does not read our overridden `h` for that), so its internal state remains consistent across frames.
+The only fine ↔ coarse boundary crossings happen at `baseLayout` entry (`h *= SCALE`) and `commitLayoutChange` exit (`Math.round(h / SCALE)` plus `snapOnRelease` overrides for aspect-square).
 
-3. **`onResizeStop`** → `commitLayoutChange` runs `snapOnRelease` first:
-   - `targetTier = nearestTier(base.w, strategy.tiers)`.
-   - Set `base.w = targetTier`, `base.h = visualSquareHFine(targetTier, ctx.containerWidth)`.
-   - Persist `grid_w = grid_h = targetTier` (coarse units; `visualSquareHFine` applies again at next idle render).
+---
 
-### Idle h derivation (`visualSquareHFine`)
+## 3. Identifying a widget's strategy
 
-The 12-col grid step (≈ container_width / 12) is wider than the fine row step (24px), so `h_coarse = w_coarse` renders rectangular. Override at render time:
+`LayoutItem` (the type RGL knows about) only has `i / x / y / w / h / min/max / static / constraints`. To find a widget's strategy from a layout item, maintain a `widgetById` map in the grid component:
 
 ```ts
-function visualSquareHFine(wCoarse: number, containerWidth: number): number {
-  if (containerWidth <= 0) return wCoarse * SCALE  // pre-mount fallback
-  const colStepPx = (containerWidth + MARGIN_X) / COLS
-  const fineRowStepPx = ROW_HEIGHT + MARGIN_Y
-  return Math.max(1, Math.round((wCoarse * colStepPx) / fineRowStepPx))
+// dashboard-grid.tsx
+const widgetById = useMemo(
+  () => new Map(widgets.map((w) => [w.id, w])),
+  [widgets]
+)
+
+function getStrategy(itemId: string): SizingStrategy {
+  const widget = widgetById.get(itemId)
+  if (!widget) return { kind: 'free' }
+  const def = WIDGET_TYPE_MAP.get(widget.widget_type)
+  return def?.sizing ?? { kind: 'free' }
 }
 ```
 
-Move this helper into `sizing-strategies/aspect-square.ts`. It is not used by any other strategy.
+`itemId` is `LayoutItem.i`, which `widgetsToLayout` sets to `widget.id`. We don't extend `LayoutItem` because RGL ships that type and a side map is one line.
 
-### `nearestTier` helper
+---
 
-```ts
-function nearestTier(value: number, tiers: number[]): number {
-  return tiers.reduce((best, t) => (Math.abs(t - value) < Math.abs(best - value) ? t : best), tiers[0])
-}
-```
+## 4. `dashboard-grid.tsx` integration
 
-Tie-break (e.g., value `3.5` with tiers `[3, 4]`): the first tier wins (`3`), which is the conservative choice (avoid accidental upgrades).
+The grid's responsibility:
 
-### `aspect-square` `applyStrategy` cases
+1. Build `baseLayout` from `widgetsToLayout(widgets)`. Apply the existing `h *= SCALE` and other fine-unit conversions.
+2. For each item: look up the strategy, run `normalizeRenderItem` for idle h/minH/maxH (Layer A), then attach `constraints` / `resizeHandles` / `isResizable` from `applyStrategy` for resize-time enforcement (Layer B).
+3. `updateLiveLayout` snaps y to coarse multiples for all items, and h to coarse multiples **only for `free` and `fixed` strategies**. Aspect-square / content-height widgets keep their constraint-derived fine h to avoid jitter from rounding the pixel-square value to a coarse boundary.
+4. `commitLayoutChange` runs `snapOnRelease` per item to produce the persistence patch (coarse units), and re-runs `normalizeRenderItem` on the live layout before `setLiveLayout` so the on-screen cell matches what the next render will produce (no visible jump on release).
 
-| ctx.interactionState | h                                                            | minH                       | maxH                       | resizeHandles |
-| -------------------- | ------------------------------------------------------------ | -------------------------- | -------------------------- | ------------- |
-| `idle`               | `visualSquareHFine(item.w, ctx.width)`                       | `visualSquareHFine(minW)`  | `visualSquareHFine(maxW)`  | `['se']`      |
-| `resizing`           | `visualSquareHFine(base.w, ctx.width)` (after `w` is updated per the drag flow) | same as idle               | same as idle               | `['se']`      |
-| `dragging`           | same as idle (resize and drag are exclusive)                 | same as idle               | same as idle               | `['se']`      |
+Sketch:
 
-### Edge cases
+```ts
+const baseLayout = useMemo(() => {
+  const layout = widgetsToLayout(widgets)
+  for (const item of layout) {
+    item.y *= SCALE
+    item.h *= SCALE
+    if (item.minH !== undefined) item.minH *= SCALE
+    if (item.maxH !== undefined) item.maxH *= SCALE
+
+    const strategy = getStrategy(item.i)
+    const measured = autoUnits[item.i]
+    const normalized = normalizeRenderItem(item, strategy, { containerWidth: width, autoMeasuredFineH: measured })
+    item.h = normalized.h
+    item.minH = normalized.minH
+    item.maxH = normalized.maxH
+
+    const desc = applyStrategy(strategy, measured)
+    item.constraints = desc.constraints
+    if (desc.resizeHandles) item.resizeHandles = desc.resizeHandles
+    if (!desc.isResizable) item.isResizable = false
+  }
+  return deoverlapLayout(layout)
+}, [widgets, autoUnits, width])
 
-- **MaxW boundary**: cursor keeps moving but `targetCoarse` is clamped to `maxW`. Cell stops at the maxW × maxW visual.
-- **Drag toward top-left**: RGL gives non-positive newW/newH. `targetCoarse` is computed as `max(...)`; if both axes shrink, it falls below `minW` and is clamped up to `minW`. Cell can't shrink below minW × minW.
-- **`preventCollision` blocks growth**: RGL refuses the new `newW`, so the layout that reaches `onResize` already has the blocked `w`. `targetCoarse` reflects that. The cell stops growing on the blocked side; the user can still grow further only if the other axis is also unblocked (because `targetCoarse` uses the larger of the two).
-- **Container width changes mid-render**: `visualSquareHFine` recomputes via the React tree. Cell visually scales with the container. `grid_w` does not change.
+const updateLiveLayout = useCallback((nextLayout) => {
+  const snapped = nextLayout.map((item) => {
+    const strategy = getStrategy(item.i)
+    const base = { ...item, y: Math.round(item.y / SCALE) * SCALE }
+    if (strategy.kind === 'free' || strategy.kind === 'fixed') {
+      // Snap h to SCALE multiples for coarse-h widgets; prevents resize jitter
+      // before the coarse persistence round-trip. Aspect-square / content-height
+      // own their fine h (constraints / measurement) so we leave it alone.
+      base.h = Math.max(SCALE, Math.round(item.h / SCALE) * SCALE)
+    }
+    return base
+  })
+  setLiveLayout(deoverlapLayout(snapped))
+}, [/* deps */])
+
+const commitLayoutChange = useCallback((finalLayout) => {
+  setInteractionState('idle')
+  const snapped = finalLayout.map((item) => {
+    const strategy = getStrategy(item.i)
+    let base = { ...item, y: Math.round(item.y / SCALE) * SCALE }
+    if (strategy.kind === 'free' || strategy.kind === 'fixed') {
+      base.h = Math.max(SCALE, Math.round(item.h / SCALE) * SCALE)
+    }
+    // Apply tier snap for aspect-square (operates in coarse, returns a coarse patch).
+    const snap = snapOnRelease(base, strategy, { containerWidth: width })
+
+    // Re-normalize so the live layout matches the next baseLayout render.
+    return normalizeRenderItem(applyCoarsePatch(base, snap), strategy, {
+      containerWidth: width,
+      autoMeasuredFineH: autoUnits[item.i]
+    })
+  })
+  setLiveLayout(deoverlapLayout(snapped))
+  const coarsePatch = snapped.map((item) => ({
+    id: item.i,
+    grid_x: item.x,
+    grid_y: Math.round(item.y / SCALE),
+    grid_w: item.w,
+    grid_h: Math.round(item.h / SCALE)
+  }))
+  // dispatch persistence …
+}, [/* deps */])
+```
+
+`applyCoarsePatch(item, patch)` is a tiny helper: takes `{ w?, h? }` in coarse units and applies them to a fine-layout item (with `h *= SCALE`). Lives in `sizing-strategies/normalize.ts`.
+
+`SQUARE_TYPES` / `AUTO_HEIGHT_TYPES` / `interactionStateRef` / `visualSquareHFine` (the inline copy) all go away.
 
 ---
 
-## 4. `content-height` strategy
+## 5. `snapOnRelease` — coarse persistence patch
 
-Behaves exactly like today's `AUTO_HEIGHT_TYPES`:
+Unit contract: returns coarse-unit `{ w?, h? }` override that the commit pipeline applies to the layout item.
 
 ```ts
-export function applyContentHeight(item, ctx): StrategyResult {
-  const measured = ctx.autoMeasuredFineH
-  if (measured !== undefined) {
-    return {
-      h: measured,
-      minH: measured,
-      maxH: measured,
-      resizeHandles: ['e'],
-      isResizable: true
+// sizing-strategies/index.ts
+export interface SnapPatch {
+  w?: number   // coarse
+  h?: number   // coarse
+}
+
+export function snapOnRelease(
+  item: LayoutItem,    // fine-unit live item
+  strategy: SizingStrategy,
+  ctx: { containerWidth: number }
+): SnapPatch {
+  switch (strategy.kind) {
+    case 'aspect-square': {
+      const tier = nearestTier(item.w, strategy.tiers)
+      return { w: tier, h: tier }   // coarse units
     }
-  }
-  const h = item.h * SCALE
-  return {
-    h,
-    minH: h,
-    maxH: h,
-    resizeHandles: ['e'],
-    isResizable: true
+    case 'free':
+    case 'fixed':
+    case 'content-height':
+      return {}
   }
 }
-```
-
-`handleMeasure` (VisibilityGate callback) keeps writing into `autoUnits`. The strategy reads from `ctx.autoMeasuredFineH`.
-
----
-
-## 5. `fixed` strategy
 
-```ts
-export function applyFixed(item, ctx): StrategyResult {
-  const h = item.h * SCALE
-  return { h, minH: h, maxH: h, resizeHandles: [], isResizable: false }
+function nearestTier(value: number, tiers: number[]): number {
+  return tiers.reduce(
+    (best, t) => (Math.abs(t - value) < Math.abs(best - value) ? t : best),
+    tiers[0]
+  )
 }
 ```
 
-Replaces the `if (minW === maxW && minH === maxH) isResizable = false` block in `dashboard-layout.ts`. `stat-number` becomes the only `fixed` widget today.
-
----
+Tie-break (e.g., value `3.5` with tiers `[3, 4]`): first tier wins (`3`) — the conservative choice (avoid accidental upgrades).
 
-## 6. `free` strategy
+`applyCoarsePatch` applies the snap to the fine-unit live item:
 
 ```ts
-export function applyFree(item, ctx): StrategyResult {
-  const minH = (item.minH ?? 1) * SCALE
-  const maxH = item.maxH !== undefined ? item.maxH * SCALE : undefined
+function applyCoarsePatch(item: LayoutItem, patch: SnapPatch): LayoutItem {
   return {
-    h: item.h * SCALE,
-    minH,
-    maxH,
-    resizeHandles: undefined,   // RGL default (all 8 corners/edges)
-    isResizable: true
+    ...item,
+    w: patch.w ?? item.w,
+    h: patch.h !== undefined ? patch.h * SCALE : item.h
   }
 }
 ```
 
-This is the no-op baseline. Most widgets use it.
+After this, `commitLayoutChange` re-runs `normalizeRenderItem` to bring the fine h back to the pixel-square value for the new w. The live layout and the next baseLayout agree.
 
 ---
 
-## 7. `widgetsToLayout` clamp pass
+## 6. `widgetsToLayout` clamp pass
 
-`dashboard-layout.ts` already clamps `grid_w` and `grid_h` to `[minW, maxW]` and `[minH, maxH]`. Extend it for `aspect-square`:
+The existing min/max clamp covers `grid_w` and `grid_h` going out of range. Extend it for `aspect-square` widgets so historical data with `grid_w !== grid_h` snaps to the nearest tier on first load:
 
 ```ts
-if (strategy.kind === 'aspect-square') {
+import { WIDGET_TYPE_MAP } from '@/lib/widget-types'
+import { nearestTier } from '@/components/dashboard/sizing-strategies'
+
+// inside widgetsToLayout, after the existing min/max clamp:
+const strategy = WIDGET_TYPE_MAP.get(widget.widget_type)?.sizing
+if (strategy?.kind === 'aspect-square') {
   const tier = nearestTier(Math.max(w, h), strategy.tiers)
   w = h = tier
 }
 ```
 
-Result: any historical widget with `grid_w !== grid_h` (or with a `grid_w` not in the tiers list) is silently corrected on first render. Persistence happens lazily on the next drag/resize, so no upfront migration is needed.
-
----
-
-## 8. `widget-types.ts` changes
-
-Add bounds to the two unbounded widgets:
-
-```diff
-- { id: 'markdown', minW: 2, minH: 2 },
-+ { id: 'markdown', minW: 2, minH: 2, maxW: 8, maxH: 8, sizing: { kind: 'free' } },
-
-- { id: 'server-cards', defaultW: 12, defaultH: 6, minW: 4, minH: 3 },
-+ { id: 'server-cards', defaultW: 12, defaultH: 6, minW: 4, minH: 3, maxW: 12, maxH: 12, sizing: { kind: 'free' } },
-```
-
-Add `sizing` to every entry.
+Render-time only; no DB write. Persistence happens lazily on the next drag/resize.
 
 ---
 
-## 9. Deletions
+## 7. Deletions
 
 The refactor removes:
 
 - `SQUARE_TYPES` constant in `dashboard-grid.tsx`
 - `AUTO_HEIGHT_TYPES` constant in `dashboard-grid.tsx`
 - `squareIdSet` and `autoIdSet` memos
-- The inline `visualSquareHFine` and its 3-place override sites (moved into `sizing-strategies/aspect-square.ts`)
+- `visualSquareHFine` and its three inline override sites (`baseLayout`, `updateLiveLayout`, `commitLayoutChange`)
+- `interactionStateRef` ref and the resizing/idle branching it gated
 - The `if (minW === maxW && minH === maxH) item.isResizable = false` block in `dashboard-layout.ts`
+- Per-strategy `base.h` overrides in `updateLiveLayout` and `commitLayoutChange`
 
-`interactionStateRef` stays — multiple strategies use it.
+The `pixelSquareFineH` formula is preserved (renamed and moved) inside `sizing-strategies/normalize.ts` — it's still needed for Layer A, just centralized.
 
 ---
 
-## 10. Internal UI adaptation (P3)
+## 8. `widget-types.ts` changes
 
-Most widgets already adapt via CSS container queries (`@container/foo`). This stays the default approach.
+Add the `sizing` field to every entry. **No bounds changes** in this iteration — existing `minW/maxW/minH/maxH` stay exactly as they are today so no user's widgets shrink unexpectedly.
 
-For the rare case where JS-driven layout switching is needed (e.g., a chart wanting to hide its legend below 200px), add a small hook:
+```diff
+  {
+    id: 'gauge',
+    ...
++   sizing: { kind: 'aspect-square', tiers: [2, 3, 4, 5, 6] },
+  },
+  {
+    id: 'top-n',
+    ...
++   sizing: { kind: 'content-height' },
+  },
+  {
+    id: 'stat-number',
+    ...
++   sizing: { kind: 'fixed' },
+  },
+  // every other widget:
++   sizing: { kind: 'free' },
+```
 
-```ts
-// apps/web/src/hooks/use-widget-size.ts
-export type SizeBucket = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+Bounds tightening for `markdown` / `server-cards` is out of scope; ship it later if needed.
 
-export interface WidgetSize {
-  width: number
-  height: number
-  bucket: SizeBucket
-}
+---
 
-export function useWidgetSize(
-  ref: RefObject<HTMLElement>,
-  buckets?: Record<SizeBucket, number>
-): WidgetSize
-```
+## 9. Testing
+
+### Unit tests (vitest)
+
+- `sizing-strategies/normalize.test.ts`
+  - `normalizeRenderItem` aspect-square: returns `h = pixelSquareFineH(w, containerWidth)`
+  - aspect-square: returns `minH = pixelSquareFineH(minW)`, `maxH = pixelSquareFineH(maxW)`
+  - content-height: when `autoMeasuredFineH` present → h/minH/maxH all = measured
+  - content-height: when measured undefined → returns item unchanged
+  - fixed: returns item unchanged
+  - free: returns item unchanged
+
+- `sizing-strategies/index.test.ts`
+  - `applyStrategy('aspect-square')` returns `constraints: [aspectRatio(1)]` and `resizeHandles: ['se']`
+  - `applyStrategy('content-height', 11)` returns `[lockHeight(11)]` and `['e']`
+  - `applyStrategy('fixed')` returns `isResizable: false`
+  - `applyStrategy('free')` returns empty constraints, undefined handles (RGL default)
+  - `snapOnRelease(aspect-square)` returns `{ w: tier, h: tier }` with `tier = nearestTier(item.w, tiers)`
+  - `snapOnRelease` for other strategies returns `{}`
+
+- `dashboard-layout.test.ts` (new)
+  - `widgetsToLayout` snaps aspect-square widgets with `grid_w !== grid_h` to the nearest tier
+  - `widgetsToLayout` preserves widgets at legal tiers
 
-Default bucket thresholds: `xs <160px, sm <240px, md <360px, lg <480px, xl ≥480px` (in widget width). Override via the `buckets` arg.
+### Manual verification
+
+New file `tests/manual/dashboard-widget-sizing.md`:
 
-The hook is **opt-in**. No existing widget is migrated. JSDoc explains "use container queries first, this hook only when CSS isn't enough".
+- Gauge resize: drag SE from 2×2 toward 6×6. The cell stays pixel-square throughout (RGL `aspectRatio(1)` constraint enforces it during drag). On release, the size snaps to the nearest tier in `[2, 3, 4, 5, 6]`.
+- Gauge mounts pixel-square (Layer A) — verify on page load before any user interaction.
+- Gauge with two side-by-side gauges: `preventCollision` blocks growth into the neighbor (existing RGL behavior).
+- Container width changes (sidebar collapse / window resize): cells visually scale, persisted `grid_w/h` unchanged.
+- Top-N: cell height tracks content via `autoMeasuredFineH`; only `e` handle visible.
+- Stat-number: not resizable, no handles.
+- Free widgets (line-chart, etc.): resize feels unchanged from today (h snaps to coarse multiples on release).
 
 ---
 
-## 11. Documentation (P2)
+## 10. Documentation
 
-New file `docs/dashboard-widget-checklist.md` (project doc, not a spec):
+New file `docs/dashboard-widget-checklist.md`:
 
 ````markdown
 # Adding a New Dashboard Widget
 
 ## Required
-1. `widget-types.ts` — `WidgetTypeDefinition` entry with `sizing` set
+1. `widget-types.ts` — `WidgetTypeDefinition` entry with `sizing` set (TS enforces this)
 2. `widget-renderer.tsx` — add the switch case
 3. `widget-picker` — icon + i18n label
 4. `widget-config-dialog.tsx` — config form (if any)
@@ -365,87 +477,51 @@ New file `docs/dashboard-widget-checklist.md` (project doc, not a spec):
 
 ## Picking a `sizing` strategy
 - Most widgets → `{ kind: 'free' }`
-- Single-value, one viable size → `{ kind: 'fixed' }`
+- Single-value, one viable size → `{ kind: 'fixed' }` (also set minW=maxW, minH=maxH)
 - Radial / gauge / aspect-locked → `{ kind: 'aspect-square', tiers: [...] }`
 - List / table with content-driven height → `{ kind: 'content-height' }`
 ````
 
 ---
 
-## 12. Testing
+## 11. Risk assessment
 
-### Unit tests (vitest)
-
-- `sizing-strategies/aspect-square.test.ts`
-  - drag mid-flight: `edge_fine = max(newW * SCALE, newH)`
-  - `snapOnRelease`: `base.w` snaps to nearest tier in tiers list
-  - clamps to `maxW` when cursor goes past
-  - clamps to `minW` when cursor goes negative
-  - persisted `grid_w === grid_h === tier`
-
-- `sizing-strategies/content-height.test.ts`
-  - `autoMeasuredFineH` takes priority over `item.h * SCALE`
-  - `resizeHandles === ['e']`
-  - `minH === maxH === h`
-
-- `sizing-strategies/fixed.test.ts`
-  - `isResizable === false`
-  - `resizeHandles === []`
-
-- `dashboard-layout.test.ts` (new)
-  - `widgetsToLayout` clamps `grid_w` past `maxW` silently
-  - `widgetsToLayout` snaps `aspect-square` widget with `grid_w !== grid_h` to the nearest tier
-
-### Manual verification
-
-New file `tests/manual/dashboard-widget-sizing.md`:
-
-- Gauge resize: drag SE from 2×2 to 6×6, releases snap to tier
-- Gauge resize: drag diagonally, cell stays square throughout
-- Gauge: window resize scales cells, persisted size unchanged
-- Top-N: cell height tracks content, only horizontal handle visible
-- Stat-number: not resizable, no handles
-- Markdown: cannot drag past width = 8 cols
-- Server-cards: cannot drag past width = 12 cols
+| Risk                                                                | Mitigation                                                                              |
+| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| Existing gauge instances with `grid_w !== grid_h` change shape      | `widgetsToLayout` snaps to nearest tier on first load. No data loss; cell looks more square — visual improvement. |
+| Refactor touches dashboard-grid core flow                           | `sizing-strategies/` is independent and unit-tested. `dashboard-grid` becomes a thin caller. |
+| RGL `aspectRatio(1)` drifts from `pixelSquareFineH`                 | We use the same formula in both. Test `pixelSquareFineH(w, width)` against `aspectRatio(1).constrainSize` output for representative widths. |
+| `react-grid-layout/core` subpath not exported in some build configs | Verified in v2.2.2 `package.json` exports. Add a type-only import test to catch regressions on upgrade. |
+| Tier snap mid-drag jumps                                            | Snap runs only in `commitLayoutChange`, not `updateLiveLayout`. Drag feels free; release snaps. |
+| Free-widget resize jitter from removing the h-snap                  | Kept: `updateLiveLayout` still snaps h to SCALE multiples for `free` and `fixed`. Only aspect-square / content-height bypass it. |
 
 ---
 
-## 13. Risk assessment
-
-| Risk                                                            | Mitigation                                                                                   |
-| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| Existing gauge instances change visual size on first render     | Silent clamp + snap. No data loss. Users see a more-square cell — visual improvement, not loss. |
-| Refactor touches the dashboard-grid core flow                   | `sizing-strategies/` is independent and unit-tested. `dashboard-grid` becomes a thin caller. |
-| Adding `maxW` to `markdown` / `server-cards` shrinks rare wides | Clamp values (8 / 12) cover the practical range. The few that exceed are clamped once.       |
-| TS discriminated union landing partially                        | `sizing` is required on `WidgetTypeDefinition`. Compile-time enforced.                       |
-
----
-
-## 14. Out of scope (deliberate)
+## 12. Out of scope (deliberate)
 
 - iOS-style multi-tier widget UIs (separate small/medium/large layouts)
 - Backend-side sizing override per widget instance
-- Per-instance aspect-ratio override (e.g., a "2:1" gauge variant)
-- Drag-time mid-snap (snap only happens on release)
-- Animation on snap-to-tier (instant)
-
-Each of these can ship later as an additional strategy or extension without breaking the model.
+- Per-instance aspect-ratio override (e.g., a 2:1 variant of gauge)
+- Drag-time mid-snap for aspect-square (snap only happens on release)
+- Animated snap-to-tier transition (instant)
+- A `useWidgetSize` hook (CSS container queries cover current widgets)
+- Tightening `markdown` / `server-cards` bounds (separate PR with migration discussion)
 
 ---
 
-## 15. File diff summary
-
-| File                                                            | Change                                                                |
-| --------------------------------------------------------------- | --------------------------------------------------------------------- |
-| `apps/web/src/lib/widget-types.ts`                              | Add `SizingStrategy` type and `sizing` field; bound markdown/server-cards |
-| `apps/web/src/components/dashboard/sizing-strategies/`          | **New** directory: 4 strategy files + `index.ts`                      |
-| `apps/web/src/components/dashboard/dashboard-grid.tsx`          | Delete `SQUARE_TYPES`/`AUTO_HEIGHT_TYPES`/`visualSquareHFine`; call `applyStrategy` |
-| `apps/web/src/components/dashboard/dashboard-layout.ts`         | Delete inline `isResizable` check; add `aspect-square` clamp pass     |
-| `apps/web/src/hooks/use-widget-size.ts`                         | **New** opt-in hook                                                   |
-| `apps/web/src/components/dashboard/widgets/gauge.tsx`           | No code change (strategy moves out of gauge.tsx and into shared dispatcher) |
-| `apps/web/src/components/dashboard/sizing-strategies/*.test.ts` | **New** vitest coverage                                               |
-| `apps/web/src/components/dashboard/dashboard-layout.test.ts`    | **New** vitest coverage for clamp paths                               |
-| `docs/dashboard-widget-checklist.md`                            | **New** contributor checklist                                         |
-| `tests/manual/dashboard-widget-sizing.md`                       | **New** manual verification checklist                                 |
-
-No backend changes. No DB migrations. No env vars.
+## 13. File diff summary
+
+| File                                                            | Change                                                                              |
+| --------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `apps/web/src/lib/widget-types.ts`                              | Add `SizingStrategy` union and the required `sizing` field on every entry           |
+| `apps/web/src/components/dashboard/sizing-strategies/`          | **New** directory: `normalize.ts` (Layer A) + `index.ts` (Layer B, exports `applyStrategy` / `snapOnRelease` / `nearestTier` / `applyCoarsePatch`) |
+| `apps/web/src/components/dashboard/sizing-strategies/normalize.test.ts` | **New** vitest for Layer A                                                  |
+| `apps/web/src/components/dashboard/sizing-strategies/index.test.ts`     | **New** vitest for Layer B                                                  |
+| `apps/web/src/components/dashboard/dashboard-grid.tsx`          | Delete `SQUARE_TYPES`/`AUTO_HEIGHT_TYPES`/`visualSquareHFine`/`interactionStateRef`; add `widgetById` map + Layer A normalize + Layer B constraints attachment; keep h snap in `updateLiveLayout` for `free` / `fixed` |
+| `apps/web/src/components/dashboard/dashboard-layout.ts`         | Delete inline `isResizable` check; add aspect-square `nearestTier` snap in `widgetsToLayout`        |
+| `apps/web/src/components/dashboard/dashboard-layout.test.ts`    | **New** vitest                                                                       |
+| `apps/web/src/components/dashboard/widgets/gauge.tsx`           | No change (strategy lives in the dispatcher)                                        |
+| `docs/dashboard-widget-checklist.md`                            | **New** contributor checklist                                                       |
+| `tests/manual/dashboard-widget-sizing.md`                       | **New** manual verification checklist                                               |
+
+No backend changes. No DB migrations. No env vars. No bounds changes to existing widget definitions.

From b0d7039eb9280699356b04b016da19a9065007bb Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 01:46:59 +0800
Subject: [PATCH 07/18] docs: add dashboard widget sizing strategy
 implementation plan

---
 ...-05-28-dashboard-widget-sizing-strategy.md | 1418 +++++++++++++++++
 1 file changed, 1418 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-05-28-dashboard-widget-sizing-strategy.md

diff --git a/docs/superpowers/plans/2026-05-28-dashboard-widget-sizing-strategy.md b/docs/superpowers/plans/2026-05-28-dashboard-widget-sizing-strategy.md
new file mode 100644
index 00000000..94f38b97
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-28-dashboard-widget-sizing-strategy.md
@@ -0,0 +1,1418 @@
+# Dashboard Widget Sizing Strategy Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace scattered widget sizing markers (`SQUARE_TYPES`, `AUTO_HEIGHT_TYPES`, inline `visualSquareHFine`, `interactionStateRef`) with an explicit `sizing` field on each widget type, backed by a two-layer dispatcher: render-time `normalizeRenderItem` for idle h, and RGL v2 `LayoutConstraint`s for resize-time enforcement.
+
+**Architecture:** Two layers. Layer A (`normalizeRenderItem`) runs in `baseLayout` to set fine-unit h / minH / maxH for aspect-square and content-height widgets at idle. Layer B attaches `LayoutConstraint`s to each `LayoutItem` so RGL's resize pipeline (`applySizeConstraints`) keeps the cell consistent during drag. Persistence and unit boundaries are explicit: only `baseLayout` does `h *= SCALE` (coarse → fine) and only `commitLayoutChange` does `Math.round(h / SCALE)` (fine → coarse).
+
+**Tech Stack:** TypeScript, React 19, react-grid-layout v2.2.2 (subpath `react-grid-layout/core` for `aspectRatio` / `LayoutConstraint`), Vitest, Tailwind v4 container queries.
+
+**Spec:** `docs/superpowers/specs/2026-05-28-dashboard-widget-sizing-strategy-design.md`
+
+---
+
+## Task 1: Extract grid constants into a shared module
+
+**Files:**
+- Create: `apps/web/src/components/dashboard/grid-constants.ts`
+- Modify: `apps/web/src/components/dashboard/dashboard-grid.tsx` (replace local constant declarations with imports)
+
+Pure refactor — no behavior change. We need these constants from two places (`dashboard-grid.tsx` and `sizing-strategies/normalize.ts`); moving them avoids a future circular import.
+
+- [ ] **Step 1: Create `apps/web/src/components/dashboard/grid-constants.ts`**
+
+```ts
+// Grid layout primitives shared between dashboard-grid.tsx and sizing-strategies/.
+// Persisted (coarse) grid rows are split into SCALE finer rows so content-sized
+// widgets quantize to ~ROW_HEIGHT px instead of a whole coarse row.
+// Invariant for pixel-identical legacy widgets: legacy per-row step
+// (80 + 16) must equal SCALE * (ROW_HEIGHT + MARGIN_Y) → 4 * (8 + 16) = 96.
+export const COLS = 12
+export const SCALE = 4
+export const ROW_HEIGHT = 8
+export const MARGIN: readonly [number, number] = [16, 16]
+export const MARGIN_X = MARGIN[0]
+export const MARGIN_Y = MARGIN[1]
+```
+
+- [ ] **Step 2: Update `apps/web/src/components/dashboard/dashboard-grid.tsx`**
+
+Find the existing constants (around lines 46-57) and replace with an import. Delete the local declarations:
+
+```ts
+// REMOVE these local declarations (lines ~46-57):
+// const COLS = 12
+// const SCALE = 4
+// const ROW_HEIGHT = 8
+// const MARGIN: [number, number] = [16, 16]
+// const MARGIN_Y = MARGIN[1]
+
+// ADD this import near the other local imports (after './widget-renderer'):
+import { COLS, MARGIN, MARGIN_Y, ROW_HEIGHT, SCALE } from './grid-constants'
+```
+
+Keep `MOBILE_ROW_PX` and `MOBILE_BREAKPOINT` local — they're not needed by sizing-strategies.
+
+- [ ] **Step 3: Run typecheck**
+
+Run: `bun run typecheck`
+Expected: passes with no errors
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add apps/web/src/components/dashboard/grid-constants.ts apps/web/src/components/dashboard/dashboard-grid.tsx
+git commit -m "refactor(web): extract dashboard grid constants for sharing"
+```
+
+---
+
+## Task 2: Add `SizingStrategy` type and `sizing` field to every widget definition
+
+**Files:**
+- Modify: `apps/web/src/lib/widget-types.ts`
+
+Type-system change. Adding `sizing: SizingStrategy` as a required field forces every widget entry to declare a strategy at compile time. No runtime change yet — nothing reads this field until Task 9.
+
+- [ ] **Step 1: Add the type and field at the top of `widget-types.ts`**
+
+After the `WidgetCategory` type and before `WidgetTypeDefinition` (around line 1):
+
+```ts
+export type WidgetCategory = 'Real-time' | 'Charts' | 'Status'
+
+export type SizingStrategy =
+  | { kind: 'free' }
+  | { kind: 'fixed' }
+  | { kind: 'aspect-square'; tiers: readonly number[] }
+  | { kind: 'content-height' }
+
+export interface WidgetTypeDefinition {
+  category: WidgetCategory
+  defaultH: number
+  defaultW: number
+  id: string
+  label: string
+  maxH?: number
+  maxW?: number
+  minH: number
+  minW: number
+  sizing: SizingStrategy
+}
+```
+
+- [ ] **Step 2: Add `sizing` to every entry in `WIDGET_TYPES`**
+
+Map each entry per the spec. The spec assigns:
+- `gauge` → `{ kind: 'aspect-square', tiers: [2, 3, 4, 5, 6] }`
+- `top-n` → `{ kind: 'content-height' }`
+- `stat-number` → `{ kind: 'fixed' }`
+- every other widget → `{ kind: 'free' }`
+
+For each `WIDGET_TYPES` entry, add `sizing: ...` as the last field. Example for the first three:
+
+```ts
+export const WIDGET_TYPES = [
+  {
+    id: 'stat-number',
+    label: 'Stat Number',
+    category: 'Real-time',
+    defaultW: 2,
+    defaultH: 1,
+    minW: 2,
+    minH: 1,
+    maxW: 2,
+    maxH: 1,
+    sizing: { kind: 'fixed' }
+  },
+  {
+    id: 'metric-card',
+    label: 'Metric Card',
+    category: 'Real-time',
+    defaultW: 4,
+    defaultH: 4,
+    minW: 3,
+    minH: 3,
+    maxW: 6,
+    maxH: 6,
+    sizing: { kind: 'free' }
+  },
+  {
+    id: 'server-cards',
+    label: 'Server Cards',
+    category: 'Real-time',
+    defaultW: 12,
+    defaultH: 6,
+    minW: 4,
+    minH: 3,
+    sizing: { kind: 'free' }
+  },
+  {
+    id: 'gauge',
+    label: 'Gauge',
+    category: 'Real-time',
+    defaultW: 2,
+    defaultH: 2,
+    minW: 2,
+    minH: 2,
+    maxW: 6,
+    maxH: 6,
+    sizing: { kind: 'aspect-square', tiers: [2, 3, 4, 5, 6] }
+  },
+  // … etc for every remaining widget
+]
+```
+
+For the remaining 10 widgets (`line-chart`, `multi-line`, `top-n`, `alert-list`, `service-status`, `traffic-bar`, `disk-io`, `server-map`, `markdown`, `uptime-timeline`): add `sizing: { kind: 'top-n' is content-height; everything else is free }`.
+
+- [ ] **Step 3: Run typecheck**
+
+Run: `bun run typecheck`
+Expected: passes. If any widget is missing `sizing`, TS will fail with "Property 'sizing' is missing".
+
+- [ ] **Step 4: Run existing frontend tests**
+
+Run: `cd apps/web && bun run test`
+Expected: passes. No tests touch `sizing` yet; this confirms we didn't break anything.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/web/src/lib/widget-types.ts
+git commit -m "feat(web): declare sizing strategy on every widget type"
+```
+
+---
+
+## Task 3: Implement `nearestTier` helper with tests
+
+**Files:**
+- Create: `apps/web/src/components/dashboard/sizing-strategies/index.ts`
+- Create: `apps/web/src/components/dashboard/sizing-strategies/index.test.ts`
+
+Smallest building block — a pure function used by aspect-square's `snapOnRelease` and by `widgetsToLayout`'s clamp pass.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `apps/web/src/components/dashboard/sizing-strategies/index.test.ts`:
+
+```ts
+import { describe, expect, it } from 'vitest'
+import { nearestTier } from './index'
+
+describe('nearestTier', () => {
+  const tiers = [2, 3, 4, 5, 6] as const
+
+  it('returns the exact tier when value matches', () => {
+    expect(nearestTier(3, tiers)).toBe(3)
+  })
+
+  it('rounds down when between two tiers, closer to lower', () => {
+    expect(nearestTier(3.4, tiers)).toBe(3)
+  })
+
+  it('rounds up when between two tiers, closer to upper', () => {
+    expect(nearestTier(3.6, tiers)).toBe(4)
+  })
+
+  it('picks the first tier on exact ties (conservative)', () => {
+    expect(nearestTier(3.5, [3, 4])).toBe(3)
+    expect(nearestTier(4.5, tiers)).toBe(4)
+  })
+
+  it('clamps to minimum tier for values below the range', () => {
+    expect(nearestTier(0, tiers)).toBe(2)
+    expect(nearestTier(-5, tiers)).toBe(2)
+  })
+
+  it('clamps to maximum tier for values above the range', () => {
+    expect(nearestTier(100, tiers)).toBe(6)
+  })
+})
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `cd apps/web && bun run test sizing-strategies/index.test.ts`
+Expected: FAIL with "Cannot find module './index'" (or similar)
+
+- [ ] **Step 3: Create the implementation**
+
+Create `apps/web/src/components/dashboard/sizing-strategies/index.ts`:
+
+```ts
+// Returns the tier closest to `value`. Ties pick the first (smaller) tier —
+// conservative bias avoids accidental upgrades when the user releases mid-drag.
+export function nearestTier(value: number, tiers: readonly number[]): number {
+  return tiers.reduce(
+    (best, t) => (Math.abs(t - value) < Math.abs(best - value) ? t : best),
+    tiers[0]
+  )
+}
+```
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run: `cd apps/web && bun run test sizing-strategies/index.test.ts`
+Expected: PASS, 6 tests
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/web/src/components/dashboard/sizing-strategies/index.ts apps/web/src/components/dashboard/sizing-strategies/index.test.ts
+git commit -m "feat(web): add nearestTier helper for sizing strategies"
+```
+
+---
+
+## Task 4: Implement `applyCoarsePatch` helper with tests
+
+**Files:**
+- Modify: `apps/web/src/components/dashboard/sizing-strategies/index.ts` (add `applyCoarsePatch`)
+- Modify: `apps/web/src/components/dashboard/sizing-strategies/index.test.ts` (add tests)
+
+`applyCoarsePatch` converts a `SnapPatch` (coarse units) into a layout item update in fine units. Used by `commitLayoutChange` after `snapOnRelease`.
+
+- [ ] **Step 1: Add failing tests**
+
+Append to `apps/web/src/components/dashboard/sizing-strategies/index.test.ts`:
+
+```ts
+import { applyCoarsePatch, type SnapPatch } from './index'
+import type { LayoutItem } from 'react-grid-layout'
+
+describe('applyCoarsePatch', () => {
+  const baseItem: LayoutItem = {
+    i: 'gauge-1',
+    x: 2,
+    y: 0,
+    w: 2,
+    h: 8        // fine units (= 2 coarse)
+  }
+
+  it('returns item unchanged when patch is empty', () => {
+    const result = applyCoarsePatch(baseItem, {})
+    expect(result.w).toBe(2)
+    expect(result.h).toBe(8)
+  })
+
+  it('applies coarse w directly (w lives in coarse units throughout)', () => {
+    const patch: SnapPatch = { w: 3 }
+    const result = applyCoarsePatch(baseItem, patch)
+    expect(result.w).toBe(3)
+    expect(result.h).toBe(8)  // unchanged
+  })
+
+  it('converts coarse h to fine by multiplying by SCALE (4)', () => {
+    const patch: SnapPatch = { h: 3 }
+    const result = applyCoarsePatch(baseItem, patch)
+    expect(result.w).toBe(2)
+    expect(result.h).toBe(12)  // 3 * 4 = 12 fine
+  })
+
+  it('applies both w and h', () => {
+    const patch: SnapPatch = { w: 4, h: 4 }
+    const result = applyCoarsePatch(baseItem, patch)
+    expect(result.w).toBe(4)
+    expect(result.h).toBe(16)
+  })
+
+  it('does not mutate the input item', () => {
+    const patch: SnapPatch = { w: 5, h: 5 }
+    applyCoarsePatch(baseItem, patch)
+    expect(baseItem.w).toBe(2)
+    expect(baseItem.h).toBe(8)
+  })
+})
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd apps/web && bun run test sizing-strategies/index.test.ts`
+Expected: FAIL with "applyCoarsePatch is not defined" or "SnapPatch is not exported"
+
+- [ ] **Step 3: Add the implementation**
+
+Add to `apps/web/src/components/dashboard/sizing-strategies/index.ts`:
+
+```ts
+import type { LayoutItem } from 'react-grid-layout'
+import { SCALE } from '../grid-constants'
+
+// A coarse-unit override returned by `snapOnRelease`. The grid layer applies
+// it to fine-unit layout items via `applyCoarsePatch`.
+export interface SnapPatch {
+  w?: number   // coarse units
+  h?: number   // coarse units (will be multiplied by SCALE when applied)
+}
+
+export function applyCoarsePatch(item: LayoutItem, patch: SnapPatch): LayoutItem {
+  return {
+    ...item,
+    w: patch.w ?? item.w,
+    h: patch.h !== undefined ? patch.h * SCALE : item.h
+  }
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd apps/web && bun run test sizing-strategies/index.test.ts`
+Expected: PASS, all 11 tests (6 nearestTier + 5 applyCoarsePatch)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/web/src/components/dashboard/sizing-strategies/index.ts apps/web/src/components/dashboard/sizing-strategies/index.test.ts
+git commit -m "feat(web): add applyCoarsePatch helper for sizing strategies"
+```
+
+---
+
+## Task 5: Implement `pixelSquareFineH` and `normalizeRenderItem` (Layer A)
+
+**Files:**
+- Create: `apps/web/src/components/dashboard/sizing-strategies/normalize.ts`
+- Create: `apps/web/src/components/dashboard/sizing-strategies/normalize.test.ts`
+
+Layer A computes idle-time h / minH / maxH for `aspect-square` (pixel-square) and `content-height` (locked to measurement) widgets.
+
+- [ ] **Step 1: Write failing tests**
+
+Create `apps/web/src/components/dashboard/sizing-strategies/normalize.test.ts`:
+
+```ts
+import { describe, expect, it } from 'vitest'
+import type { LayoutItem } from 'react-grid-layout'
+import type { SizingStrategy } from '@/lib/widget-types'
+import { normalizeRenderItem, pixelSquareFineH } from './normalize'
+
+const W_AT_1004 = 1004  // a representative container width
+
+describe('pixelSquareFineH', () => {
+  it('returns wCoarse * SCALE when containerWidth is non-positive', () => {
+    expect(pixelSquareFineH(2, 0)).toBe(8)
+    expect(pixelSquareFineH(3, -100)).toBe(12)
+  })
+
+  it('returns pixel-square fine h at typical container width', () => {
+    // At 1004px: colStepPx = (1004+16)/12 = 85; fineRowStepPx = 8+16 = 24
+    // pixelSquareFineH(2) = round(2 * 85 / 24) = round(7.083) = 7
+    expect(pixelSquareFineH(2, W_AT_1004)).toBe(7)
+    // pixelSquareFineH(3) = round(3 * 85 / 24) = round(10.625) = 11
+    expect(pixelSquareFineH(3, W_AT_1004)).toBe(11)
+    // pixelSquareFineH(6) = round(6 * 85 / 24) = round(21.25) = 21
+    expect(pixelSquareFineH(6, W_AT_1004)).toBe(21)
+  })
+
+  it('never returns less than 1', () => {
+    expect(pixelSquareFineH(0, W_AT_1004)).toBe(1)
+  })
+})
+
+describe('normalizeRenderItem', () => {
+  const baseItem: LayoutItem = {
+    i: 'widget-1',
+    x: 0,
+    y: 0,
+    w: 2,
+    h: 8,           // fine units
+    minW: 2,
+    minH: 8,
+    maxW: 6,
+    maxH: 24
+  }
+
+  it('returns aspect-square h derived from w', () => {
+    const strategy: SizingStrategy = { kind: 'aspect-square', tiers: [2, 3, 4, 5, 6] }
+    const result = normalizeRenderItem(baseItem, strategy, { containerWidth: W_AT_1004 })
+    expect(result.h).toBe(7)              // pixelSquareFineH(2, 1004)
+    expect(result.minH).toBe(7)           // pixelSquareFineH(minW=2, 1004)
+    expect(result.maxH).toBe(21)          // pixelSquareFineH(maxW=6, 1004)
+  })
+
+  it('aspect-square leaves w/x/y/minW/maxW unchanged', () => {
+    const strategy: SizingStrategy = { kind: 'aspect-square', tiers: [2, 3, 4, 5, 6] }
+    const result = normalizeRenderItem(baseItem, strategy, { containerWidth: W_AT_1004 })
+    expect(result.w).toBe(2)
+    expect(result.x).toBe(0)
+    expect(result.minW).toBe(2)
+    expect(result.maxW).toBe(6)
+  })
+
+  it('content-height uses measured fine h when present', () => {
+    const strategy: SizingStrategy = { kind: 'content-height' }
+    const result = normalizeRenderItem(baseItem, strategy, {
+      containerWidth: W_AT_1004,
+      autoMeasuredFineH: 11
+    })
+    expect(result.h).toBe(11)
+    expect(result.minH).toBe(11)
+    expect(result.maxH).toBe(11)
+  })
+
+  it('content-height returns item unchanged when measurement is missing', () => {
+    const strategy: SizingStrategy = { kind: 'content-height' }
+    const result = normalizeRenderItem(baseItem, strategy, { containerWidth: W_AT_1004 })
+    expect(result.h).toBe(8)              // unchanged
+    expect(result.minH).toBe(8)
+    expect(result.maxH).toBe(24)
+  })
+
+  it('free returns item unchanged', () => {
+    const strategy: SizingStrategy = { kind: 'free' }
+    const result = normalizeRenderItem(baseItem, strategy, { containerWidth: W_AT_1004 })
+    expect(result.h).toBe(8)
+    expect(result.minH).toBe(8)
+    expect(result.maxH).toBe(24)
+  })
+
+  it('fixed returns item unchanged', () => {
+    const strategy: SizingStrategy = { kind: 'fixed' }
+    const result = normalizeRenderItem(baseItem, strategy, { containerWidth: W_AT_1004 })
+    expect(result.h).toBe(8)
+    expect(result.minH).toBe(8)
+    expect(result.maxH).toBe(24)
+  })
+
+  it('aspect-square handles undefined maxW gracefully', () => {
+    const strategy: SizingStrategy = { kind: 'aspect-square', tiers: [2, 3, 4, 5, 6] }
+    const itemNoMaxW: LayoutItem = { ...baseItem, maxW: undefined, maxH: undefined }
+    const result = normalizeRenderItem(itemNoMaxW, strategy, { containerWidth: W_AT_1004 })
+    expect(result.maxH).toBeUndefined()
+  })
+})
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd apps/web && bun run test sizing-strategies/normalize.test.ts`
+Expected: FAIL with "Cannot find module './normalize'"
+
+- [ ] **Step 3: Create the implementation**
+
+Create `apps/web/src/components/dashboard/sizing-strategies/normalize.ts`:
+
+```ts
+import type { LayoutItem } from 'react-grid-layout'
+import type { SizingStrategy } from '@/lib/widget-types'
+import { COLS, MARGIN_X, MARGIN_Y, ROW_HEIGHT, SCALE } from '../grid-constants'
+
+export interface NormalizeContext {
+  containerWidth: number
+  autoMeasuredFineH?: number   // populated for content-height widgets via ResizeObserver
+}
+
+// Same formula RGL's aspectRatio(1) uses internally (see
+// react-grid-layout@2.2.2/dist/chunk-XYPIYYYQ.mjs:61). Replicated here so we can
+// apply it at idle render time — RGL constraints only run during resize.
+export function pixelSquareFineH(wCoarse: number, containerWidth: number): number {
+  if (containerWidth <= 0) {
+    return wCoarse * SCALE
+  }
+  const colStepPx = (containerWidth + MARGIN_X) / COLS
+  const fineRowStepPx = ROW_HEIGHT + MARGIN_Y
+  return Math.max(1, Math.round((wCoarse * colStepPx) / fineRowStepPx))
+}
+
+// Applies strategy-specific overrides to a fine-unit layout item.
+// Operates entirely in fine units (caller has already done `h *= SCALE`).
+// Returns a NEW item — never mutates the input.
+export function normalizeRenderItem(
+  item: LayoutItem,
+  strategy: SizingStrategy,
+  ctx: NormalizeContext
+): LayoutItem {
+  switch (strategy.kind) {
+    case 'aspect-square': {
+      const h = pixelSquareFineH(item.w, ctx.containerWidth)
+      const minH = pixelSquareFineH(item.minW ?? 2, ctx.containerWidth)
+      const maxH =
+        item.maxW !== undefined
+          ? pixelSquareFineH(item.maxW, ctx.containerWidth)
+          : undefined
+      return { ...item, h, minH, maxH }
+    }
+    case 'content-height': {
+      const measured = ctx.autoMeasuredFineH
+      if (measured !== undefined) {
+        return { ...item, h: measured, minH: measured, maxH: measured }
+      }
+      return item
+    }
+    case 'fixed':
+    case 'free':
+      return item
+  }
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd apps/web && bun run test sizing-strategies/normalize.test.ts`
+Expected: PASS, all 11 tests
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/web/src/components/dashboard/sizing-strategies/normalize.ts apps/web/src/components/dashboard/sizing-strategies/normalize.test.ts
+git commit -m "feat(web): add normalizeRenderItem for idle widget sizing (layer A)"
+```
+
+---
+
+## Task 6: Implement `applyStrategy` (Layer B) with `lockHeight` constraint
+
+**Files:**
+- Modify: `apps/web/src/components/dashboard/sizing-strategies/index.ts`
+- Modify: `apps/web/src/components/dashboard/sizing-strategies/index.test.ts`
+
+Layer B returns `LayoutConstraint`s + resize handle config that attaches per-item. RGL's pipeline applies them during resize.
+
+- [ ] **Step 1: Verify the subpath export resolves**
+
+Run: `node -e "console.log(Object.keys(require('react-grid-layout/core')).filter(k => k === 'aspectRatio' || k === 'snapToGrid').sort())"`
+Expected: `[ 'aspectRatio' ]` (snapToGrid not used by us but proves the path resolves; aspectRatio is the one we need)
+
+If the output is empty or the require fails, run `cd apps/web && bun install` first and re-check.
+
+- [ ] **Step 2: Append failing tests**
+
+Append to `apps/web/src/components/dashboard/sizing-strategies/index.test.ts`:
+
+```ts
+import { applyStrategy } from './index'
+import type { SizingStrategy } from '@/lib/widget-types'
+
+describe('applyStrategy', () => {
+  it('free returns no constraints and undefined resize handles', () => {
+    const strategy: SizingStrategy = { kind: 'free' }
+    const desc = applyStrategy(strategy)
+    expect(desc.constraints).toEqual([])
+    expect(desc.resizeHandles).toBeUndefined()
+    expect(desc.isResizable).toBe(true)
+  })
+
+  it('fixed returns no constraints, empty resize handles, isResizable false', () => {
+    const strategy: SizingStrategy = { kind: 'fixed' }
+    const desc = applyStrategy(strategy)
+    expect(desc.constraints).toEqual([])
+    expect(desc.resizeHandles).toEqual([])
+    expect(desc.isResizable).toBe(false)
+  })
+
+  it('aspect-square returns aspectRatio(1) constraint and SE handle', () => {
+    const strategy: SizingStrategy = { kind: 'aspect-square', tiers: [2, 3, 4, 5, 6] }
+    const desc = applyStrategy(strategy)
+    expect(desc.constraints).toHaveLength(1)
+    expect(desc.constraints[0].name).toBe('aspectRatio(1)')
+    expect(desc.resizeHandles).toEqual(['se'])
+    expect(desc.isResizable).toBe(true)
+  })
+
+  it('content-height returns lockHeight constraint when measured', () => {
+    const strategy: SizingStrategy = { kind: 'content-height' }
+    const desc = applyStrategy(strategy, 11)
+    expect(desc.constraints).toHaveLength(1)
+    expect(desc.constraints[0].name).toBe('lockHeight(11)')
+    expect(desc.resizeHandles).toEqual(['e'])
+    expect(desc.isResizable).toBe(true)
+  })
+
+  it('content-height returns no constraint when unmeasured', () => {
+    const strategy: SizingStrategy = { kind: 'content-height' }
+    const desc = applyStrategy(strategy)
+    expect(desc.constraints).toEqual([])
+    expect(desc.resizeHandles).toEqual(['e'])
+    expect(desc.isResizable).toBe(true)
+  })
+
+  it('lockHeight constraint locks h to the measured value', () => {
+    const strategy: SizingStrategy = { kind: 'content-height' }
+    const desc = applyStrategy(strategy, 11)
+    const constraint = desc.constraints[0]
+    // Call the constraint directly — params: item, w, h, handle, context
+    const result = constraint.constrainSize?.(
+      { i: 'x', x: 0, y: 0, w: 4, h: 99 },
+      4,
+      99,
+      'e',
+      { cols: 12, containerWidth: 1000, maxRows: Infinity, rowHeight: 8, margin: [16, 16], layout: [] } as any
+    )
+    expect(result).toEqual({ w: 4, h: 11 })
+  })
+})
+```
+
+- [ ] **Step 3: Run tests to verify they fail**
+
+Run: `cd apps/web && bun run test sizing-strategies/index.test.ts`
+Expected: FAIL with "applyStrategy is not defined" or similar
+
+- [ ] **Step 4: Add the implementation**
+
+Append to `apps/web/src/components/dashboard/sizing-strategies/index.ts`:
+
+```ts
+import { aspectRatio } from 'react-grid-layout/core'
+import type { LayoutConstraint, ResizeHandleAxis } from 'react-grid-layout/core'
+import type { SizingStrategy } from '@/lib/widget-types'
+
+export interface StrategyDescriptor {
+  // Constraints attached to LayoutItem.constraints. Applied by RGL inside
+  // applySizeConstraints during the resize pipeline. NOT applied at idle
+  // layout sync — use `normalizeRenderItem` for idle h.
+  constraints: LayoutConstraint[]
+
+  // Which resize handles to render. undefined = RGL default (all 8 corners/edges).
+  resizeHandles?: ResizeHandleAxis[]
+
+  // Whether the item participates in resize at all.
+  isResizable: boolean
+}
+
+function lockHeight(fineH: number): LayoutConstraint {
+  return {
+    name: `lockHeight(${fineH})`,
+    constrainSize(_item, w) {
+      return { w, h: fineH }
+    }
+  }
+}
+
+export function applyStrategy(
+  strategy: SizingStrategy,
+  measuredFineH?: number
+): StrategyDescriptor {
+  switch (strategy.kind) {
+    case 'free':
+      return { constraints: [], resizeHandles: undefined, isResizable: true }
+    case 'fixed':
+      return { constraints: [], resizeHandles: [], isResizable: false }
+    case 'aspect-square':
+      return { constraints: [aspectRatio(1)], resizeHandles: ['se'], isResizable: true }
+    case 'content-height':
+      return {
+        constraints: measuredFineH !== undefined ? [lockHeight(measuredFineH)] : [],
+        resizeHandles: ['e'],
+        isResizable: true
+      }
+  }
+}
+```
+
+- [ ] **Step 5: Run tests to verify they pass**
+
+Run: `cd apps/web && bun run test sizing-strategies/index.test.ts`
+Expected: PASS, all 17 tests (6 nearestTier + 5 applyCoarsePatch + 6 applyStrategy)
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add apps/web/src/components/dashboard/sizing-strategies/index.ts apps/web/src/components/dashboard/sizing-strategies/index.test.ts
+git commit -m "feat(web): add applyStrategy with RGL constraints (layer B)"
+```
+
+---
+
+## Task 7: Implement `snapOnRelease`
+
+**Files:**
+- Modify: `apps/web/src/components/dashboard/sizing-strategies/index.ts`
+- Modify: `apps/web/src/components/dashboard/sizing-strategies/index.test.ts`
+
+`snapOnRelease` produces a coarse-unit `SnapPatch` for aspect-square widgets at the end of a resize. Other strategies return an empty patch.
+
+- [ ] **Step 1: Append failing tests**
+
+Append to `apps/web/src/components/dashboard/sizing-strategies/index.test.ts`:
+
+```ts
+import { snapOnRelease } from './index'
+
+describe('snapOnRelease', () => {
+  const baseItem: LayoutItem = {
+    i: 'gauge-1',
+    x: 0,
+    y: 0,
+    w: 3,
+    h: 11      // fine units
+  }
+
+  it('aspect-square snaps w to the nearest tier and returns coarse h = w', () => {
+    const strategy: SizingStrategy = { kind: 'aspect-square', tiers: [2, 3, 4, 5, 6] }
+    const result = snapOnRelease({ ...baseItem, w: 4 }, strategy, { containerWidth: 1004 })
+    expect(result).toEqual({ w: 4, h: 4 })
+  })
+
+  it('aspect-square snaps non-tier w to nearest', () => {
+    const strategy: SizingStrategy = { kind: 'aspect-square', tiers: [2, 3, 4, 5, 6] }
+    // base.w shouldn't be fractional in practice, but commitLayoutChange
+    // may receive a w just above a tier boundary during dragging — verify snap.
+    const result = snapOnRelease({ ...baseItem, w: 3 }, strategy, { containerWidth: 1004 })
+    expect(result).toEqual({ w: 3, h: 3 })
+  })
+
+  it('free returns empty patch', () => {
+    const strategy: SizingStrategy = { kind: 'free' }
+    expect(snapOnRelease(baseItem, strategy, { containerWidth: 1004 })).toEqual({})
+  })
+
+  it('fixed returns empty patch', () => {
+    const strategy: SizingStrategy = { kind: 'fixed' }
+    expect(snapOnRelease(baseItem, strategy, { containerWidth: 1004 })).toEqual({})
+  })
+
+  it('content-height returns empty patch', () => {
+    const strategy: SizingStrategy = { kind: 'content-height' }
+    expect(snapOnRelease(baseItem, strategy, { containerWidth: 1004 })).toEqual({})
+  })
+})
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd apps/web && bun run test sizing-strategies/index.test.ts`
+Expected: FAIL with "snapOnRelease is not defined"
+
+- [ ] **Step 3: Add the implementation**
+
+Append to `apps/web/src/components/dashboard/sizing-strategies/index.ts`:
+
+```ts
+export interface SnapContext {
+  containerWidth: number
+}
+
+export function snapOnRelease(
+  item: LayoutItem,
+  strategy: SizingStrategy,
+  _ctx: SnapContext
+): SnapPatch {
+  switch (strategy.kind) {
+    case 'aspect-square': {
+      const tier = nearestTier(item.w, strategy.tiers)
+      return { w: tier, h: tier }
+    }
+    case 'free':
+    case 'fixed':
+    case 'content-height':
+      return {}
+  }
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd apps/web && bun run test sizing-strategies/index.test.ts`
+Expected: PASS, all 22 tests
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/web/src/components/dashboard/sizing-strategies/index.ts apps/web/src/components/dashboard/sizing-strategies/index.test.ts
+git commit -m "feat(web): add snapOnRelease for aspect-square tier snap"
+```
+
+---
+
+## Task 8: Add aspect-square clamp pass in `widgetsToLayout`
+
+**Files:**
+- Modify: `apps/web/src/components/dashboard/dashboard-layout.ts`
+- Create: `apps/web/src/components/dashboard/dashboard-layout.test.ts`
+
+When old data has `grid_w !== grid_h` for an aspect-square widget, snap to the nearest tier on first load. No DB write — render-time only.
+
+- [ ] **Step 1: Write failing test**
+
+Create `apps/web/src/components/dashboard/dashboard-layout.test.ts`:
+
+```ts
+import { describe, expect, it } from 'vitest'
+import type { DashboardWidget } from '@/lib/widget-types'
+import { widgetsToLayout } from './dashboard-layout'
+
+function makeWidget(overrides: Partial<DashboardWidget>): DashboardWidget {
+  return {
+    id: 'w1',
+    dashboard_id: 'd1',
+    widget_type: 'gauge',
+    grid_x: 0,
+    grid_y: 0,
+    grid_w: 2,
+    grid_h: 2,
+    sort_order: 0,
+    title: null,
+    config_json: '{}',
+    created_at: '2026-05-28T00:00:00Z',
+    ...overrides
+  }
+}
+
+describe('widgetsToLayout', () => {
+  describe('aspect-square clamp', () => {
+    it('snaps a non-square gauge to the nearest tier (uses max of w/h)', () => {
+      // grid_w=3, grid_h=5 → max=5 → nearest tier in [2,3,4,5,6] is 5
+      const widget = makeWidget({ grid_w: 3, grid_h: 5 })
+      const [item] = widgetsToLayout([widget])
+      expect(item.w).toBe(5)
+      expect(item.h).toBe(5)
+    })
+
+    it('preserves a gauge already at a legal tier', () => {
+      const widget = makeWidget({ grid_w: 4, grid_h: 4 })
+      const [item] = widgetsToLayout([widget])
+      expect(item.w).toBe(4)
+      expect(item.h).toBe(4)
+    })
+
+    it('clamps an oversized gauge to maxW tier', () => {
+      // grid_w=10 → clamped to maxW=6 by existing logic → tier=6
+      const widget = makeWidget({ grid_w: 10, grid_h: 10 })
+      const [item] = widgetsToLayout([widget])
+      expect(item.w).toBe(6)
+      expect(item.h).toBe(6)
+    })
+
+    it('does not snap non-aspect-square widgets', () => {
+      // metric-card is free; should keep grid_w/h as-is (within min/max)
+      const widget = makeWidget({ widget_type: 'metric-card', grid_w: 4, grid_h: 3 })
+      const [item] = widgetsToLayout([widget])
+      expect(item.w).toBe(4)
+      expect(item.h).toBe(3)
+    })
+  })
+})
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd apps/web && bun run test dashboard-layout.test.ts`
+Expected: FAIL — the gauge snap won't happen yet
+
+- [ ] **Step 3: Update `widgetsToLayout` in `dashboard-layout.ts`**
+
+Read the file to find the existing clamp logic (around line 36-44). Add the aspect-square snap after the clamp. Also remove the `if (maxW === minW && maxH === minH) isResizable = false` block at the bottom (Task 9 picks that up via the `fixed` strategy).
+
+The full updated function looks like:
+
+```ts
+import type { Layout, LayoutItem } from 'react-grid-layout'
+import { type DashboardWidget, WIDGET_TYPES, type WidgetTypeDefinition } from '@/lib/widget-types'
+import { nearestTier } from './sizing-strategies'
+
+// (existing code stays)
+
+const WIDGET_TYPE_MAP = new Map<string, WidgetTypeDefinition>(
+  WIDGET_TYPES.map((widget) => [widget.id, widget])
+)
+
+function getSizeConstraints(widgetType: string) {
+  const definition = WIDGET_TYPE_MAP.get(widgetType)
+  return {
+    minW: definition?.minW ?? 2,
+    minH: definition?.minH ?? 2,
+    maxW: definition?.maxW,
+    maxH: definition?.maxH
+  }
+}
+
+function isWidgetStatic(configJson: string): boolean {
+  try {
+    const config = JSON.parse(configJson)
+    return config?.is_static === true
+  } catch {
+    return false
+  }
+}
+
+export function widgetsToLayout(widgets: DashboardWidget[]): Layout {
+  return widgets.map((widget) => {
+    const { minW, minH, maxW, maxH } = getSizeConstraints(widget.widget_type)
+    let w = Math.max(widget.grid_w, minW)
+    let h = Math.max(widget.grid_h, minH)
+    if (maxW !== undefined) w = Math.min(w, maxW)
+    if (maxH !== undefined) h = Math.min(h, maxH)
+
+    // Aspect-square widgets persist as w_coarse === h_coarse. If historical data
+    // somehow has them out of sync (or grid_w not at a legal tier), snap here so
+    // the cell renders square on first load. Next user drag/resize writes back.
+    const sizing = WIDGET_TYPE_MAP.get(widget.widget_type)?.sizing
+    if (sizing?.kind === 'aspect-square') {
+      const tier = nearestTier(Math.max(w, h), sizing.tiers)
+      w = tier
+      h = tier
+    }
+
+    const item: LayoutItem = {
+      i: widget.id,
+      x: widget.grid_x,
+      y: widget.grid_y,
+      w,
+      h,
+      minW,
+      minH
+    }
+    if (maxW !== undefined) item.maxW = maxW
+    if (maxH !== undefined) item.maxH = maxH
+    if (isWidgetStatic(widget.config_json)) {
+      item.static = true
+    }
+    return item
+  })
+}
+```
+
+Note: the old `if (maxW !== undefined && maxH !== undefined && minW === maxW && minH === maxH) item.isResizable = false` is **removed**. Task 9 sets `isResizable: false` via the `fixed` strategy descriptor.
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd apps/web && bun run test dashboard-layout.test.ts`
+Expected: PASS, 4 tests
+
+- [ ] **Step 5: Run typecheck and all tests**
+
+Run: `bun run typecheck && cd apps/web && bun run test`
+Expected: passes. The deleted `isResizable` block isn't covered by tests yet — Task 9 picks it up via strategy.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add apps/web/src/components/dashboard/dashboard-layout.ts apps/web/src/components/dashboard/dashboard-layout.test.ts
+git commit -m "feat(web): snap aspect-square widgets to nearest tier in widgetsToLayout"
+```
+
+---
+
+## Task 9: Refactor `dashboard-grid.tsx` to use the strategy dispatcher
+
+**Files:**
+- Modify: `apps/web/src/components/dashboard/dashboard-grid.tsx`
+
+This is the central refactor. We delete `SQUARE_TYPES`, `AUTO_HEIGHT_TYPES`, `squareIdSet`, `autoIdSet`, `visualSquareHFine`, `interactionStateRef`, and the per-strategy branching in `baseLayout` / `updateLiveLayout` / `commitLayoutChange`. We replace them with a `widgetById` map + `getStrategy` lookup + `normalizeRenderItem` + `applyStrategy` + `snapOnRelease` + `applyCoarsePatch`.
+
+No unit tests for this file — it's a thin orchestrator over the strategy modules (which are tested) and RGL itself. We verify manually in Task 10 via `make dev-demo`.
+
+- [ ] **Step 1: Read the current file to anchor the edits**
+
+Run: `wc -l apps/web/src/components/dashboard/dashboard-grid.tsx`
+Note the current line count. Expect around 460 lines.
+
+- [ ] **Step 2: Delete the strategy markers and `visualSquareHFine`**
+
+In `apps/web/src/components/dashboard/dashboard-grid.tsx`:
+
+1. Delete lines containing `AUTO_HEIGHT_TYPES` (the constant declaration around line 60-61) and `SQUARE_TYPES` (around line 63-65).
+2. Delete the `visualSquareHFine` `useCallback` block (around lines 197-212).
+3. Delete the `squareIdSet` `useMemo` (lines 192-195).
+4. Delete `autoIdSet` `useMemo` (around lines 244-247).
+5. Delete `interactionStateRef` declaration and assignment (around lines 256-260).
+
+(You'll add their replacements in the next steps. The file may not compile in between — that's fine, we'll get it back together in Step 5.)
+
+- [ ] **Step 3: Add strategy lookup infrastructure**
+
+After the `useContainerWidth` hook call (around line 183), add the widget map and strategy lookup. Also import the needed helpers.
+
+Top of file, add to imports:
+
+```ts
+import { WIDGET_TYPES } from '@/lib/widget-types'
+import type { SizingStrategy, WidgetTypeDefinition } from '@/lib/widget-types'
+import { applyStrategy, applyCoarsePatch, snapOnRelease } from './sizing-strategies'
+import { normalizeRenderItem } from './sizing-strategies/normalize'
+```
+
+Add a module-level map (outside the component, near other module-level constants like `COLS`):
+
+```ts
+const WIDGET_TYPE_MAP = new Map<string, WidgetTypeDefinition>(
+  WIDGET_TYPES.map((widget) => [widget.id, widget])
+)
+```
+
+Inside the component, after `const [autoUnits, setAutoUnits] = useState<...>({})`:
+
+```ts
+const widgetById = useMemo(
+  () => new Map(widgets.map((w) => [w.id, w])),
+  [widgets]
+)
+
+const getStrategy = useCallback(
+  (itemId: string): SizingStrategy => {
+    const widget = widgetById.get(itemId)
+    if (!widget) return { kind: 'free' }
+    const def = WIDGET_TYPE_MAP.get(widget.widget_type)
+    return def?.sizing ?? { kind: 'free' }
+  },
+  [widgetById]
+)
+```
+
+- [ ] **Step 4: Rewrite `baseLayout`**
+
+Replace the entire `baseLayout` `useMemo` block with this implementation:
+
+```ts
+const baseLayout = useMemo(() => {
+  const layout = widgetsToLayout(widgets)
+  for (const item of layout) {
+    item.y *= SCALE
+    item.h *= SCALE
+    if (item.minH !== undefined) item.minH *= SCALE
+    if (item.maxH !== undefined) item.maxH *= SCALE
+
+    const strategy = getStrategy(item.i)
+    const measured = autoUnits[item.i]
+
+    // Layer A: idle h / minH / maxH per strategy
+    const normalized = normalizeRenderItem(item, strategy, {
+      containerWidth: width,
+      autoMeasuredFineH: measured
+    })
+    item.h = normalized.h
+    item.minH = normalized.minH
+    item.maxH = normalized.maxH
+
+    // Layer B: resize-time constraints, handles, resizability
+    const desc = applyStrategy(strategy, measured)
+    if (desc.constraints.length > 0) item.constraints = desc.constraints
+    if (desc.resizeHandles) item.resizeHandles = desc.resizeHandles
+    if (!desc.isResizable) item.isResizable = false
+  }
+  return deoverlapLayout(layout)
+}, [widgets, autoUnits, width, getStrategy])
+```
+
+- [ ] **Step 5: Rewrite `updateLiveLayout`**
+
+Find the existing `updateLiveLayout` `useCallback` and replace its body. The new version uses strategy to decide whether to snap h to coarse multiples (only `free` and `fixed` need this; aspect-square and content-height own their fine h):
+
+```ts
+const updateLiveLayout = useCallback(
+  (nextLayout: Layout) => {
+    const snapped = nextLayout.map((item) => {
+      const strategy = getStrategy(item.i)
+      const base = {
+        ...item,
+        y: Math.round(item.y / SCALE) * SCALE
+      }
+      // Snap h to SCALE multiples only for strategies that operate at coarse h.
+      // aspect-square: h is fine pixel-square (constraints handle resize); leave it.
+      // content-height: h locked to measurement; leave it.
+      if (strategy.kind === 'free' || strategy.kind === 'fixed') {
+        base.h = Math.max(SCALE, Math.round(item.h / SCALE) * SCALE)
+      }
+      return base
+    })
+    setLiveLayout(deoverlapLayout(snapped))
+  },
+  [getStrategy]
+)
+```
+
+- [ ] **Step 6: Rewrite `commitLayoutChange`**
+
+Replace its body:
+
+```ts
+const commitLayoutChange = useCallback(
+  (finalLayout: Layout) => {
+    setInteractionState('idle')
+
+    // Per-strategy: snap to coarse boundaries (free/fixed), then apply
+    // snapOnRelease's coarse SnapPatch via applyCoarsePatch, then re-normalize
+    // so the live layout matches what the next baseLayout render will produce.
+    const snapped = finalLayout.map((item) => {
+      const strategy = getStrategy(item.i)
+      const measured = autoUnits[item.i]
+
+      let base = {
+        ...item,
+        y: Math.round(item.y / SCALE) * SCALE
+      }
+      if (strategy.kind === 'free' || strategy.kind === 'fixed') {
+        base.h = Math.max(SCALE, Math.round(item.h / SCALE) * SCALE)
+      }
+
+      const snap = snapOnRelease(base, strategy, { containerWidth: width })
+      base = applyCoarsePatch(base, snap)
+      return normalizeRenderItem(base, strategy, {
+        containerWidth: width,
+        autoMeasuredFineH: measured
+      })
+    })
+    const resolved = deoverlapLayout(snapped)
+    setLiveLayout(resolved)
+
+    const coarseLayout = resolved.map((item) => ({
+      ...item,
+      y: Math.round(item.y / SCALE),
+      h: Math.round(item.h / SCALE)
+    }))
+    const patch = layoutToPatch(coarseLayout, widgets)
+    if (patch.length > 0) {
+      onLayoutChange(patch)
+    }
+  },
+  [autoUnits, getStrategy, onLayoutChange, widgets, width]
+)
+```
+
+- [ ] **Step 7: Run typecheck**
+
+Run: `bun run typecheck`
+Expected: passes. If any references to `SQUARE_TYPES`, `AUTO_HEIGHT_TYPES`, `visualSquareHFine`, `squareIdSet`, `autoIdSet`, or `interactionStateRef` remain, TS will flag them.
+
+- [ ] **Step 8: Run all frontend tests**
+
+Run: `cd apps/web && bun run test`
+Expected: passes. Existing widget tests should not be affected.
+
+- [ ] **Step 9: Run lint**
+
+Run: `bun x ultracite check`
+Expected: passes. If imports got out of order or there are unused imports left over from the deletions, this catches them.
+
+- [ ] **Step 10: Commit**
+
+```bash
+git add apps/web/src/components/dashboard/dashboard-grid.tsx
+git commit -m "refactor(web): route dashboard grid sizing through strategy dispatcher
+
+Replace SQUARE_TYPES / AUTO_HEIGHT_TYPES / visualSquareHFine /
+interactionStateRef with widgetById + getStrategy + normalizeRenderItem
+(layer A, idle) + applyStrategy (layer B, RGL constraints). Per-strategy
+h snap in updateLiveLayout/commitLayoutChange replaces the inline
+overrides. snapOnRelease + applyCoarsePatch land aspect-square tier
+snaps on resize end."
+```
+
+---
+
+## Task 10: Manual verification with `make dev-demo`
+
+**Files:**
+- None directly modified. We just exercise the UI.
+
+The strategy infrastructure has unit tests, but the integration with RGL needs a real browser. `make dev-demo` (admin/admin123, demo data) is the fastest way.
+
+- [ ] **Step 1: Start the demo environment**
+
+Run: `make dev-demo`
+
+Wait for the script to print `Demo data is ready` and the Vite dev server URL. Open the URL in a browser. Log in as `admin / admin123`.
+
+- [ ] **Step 2: Verify gauge renders pixel-square on mount**
+
+Navigate to a dashboard that has at least one gauge widget (the demo dashboards should). Without interacting, measure the gauge's cell rectangle. It should be visually pixel-square (1:1).
+
+If the cell is rectangular (taller than wide), `normalizeRenderItem` is not being applied — re-check Task 9 Step 4.
+
+- [ ] **Step 3: Verify gauge resize feels right**
+
+Click "Edit" to enter edit mode. Drag a gauge's SE handle:
+- During the drag, the cell stays pixel-square (RGL `aspectRatio(1)` enforces this).
+- The cell follows the cursor in whichever axis is larger.
+- Drag right enough → w advances by one tier (visually).
+- Release → cell snaps to the nearest tier (2/3/4/5/6 coarse, depending on cursor).
+
+If the cell goes rectangular during drag, the `applyStrategy` constraints aren't being attached to `item.constraints` — re-check Task 9 Step 4.
+
+- [ ] **Step 4: Verify gauge persistence**
+
+After resizing and releasing, exit edit mode. Reload the page. The gauge should come back at the same tier you released. Confirms `commitLayoutChange` is producing a correct coarse patch via `snapOnRelease` → `layoutToPatch`.
+
+- [ ] **Step 5: Verify content-height widget (top-n)**
+
+Navigate to a dashboard with a Top-N widget. In edit mode, only the east (`e`) handle should be visible. Width resize works; height is locked to content. Confirms `applyContentHeight` with measured value attached the `lockHeight` constraint and `resizeHandles: ['e']`.
+
+- [ ] **Step 6: Verify fixed widget (stat-number)**
+
+Navigate to a dashboard with a Stat Number widget. In edit mode, no resize handles should appear. Confirms `applyStrategy({kind:'fixed'})` set `isResizable: false`.
+
+- [ ] **Step 7: Verify free widgets (line-chart, etc.)**
+
+Resize a line-chart widget. All 8 handles should be available. Resize works without issues. h snaps to coarse multiples on release (look for clean integer pixel values, not random fine offsets).
+
+- [ ] **Step 8: Check browser console for errors**
+
+Open DevTools → Console. There should be no errors. In particular, no "Maximum update depth exceeded" warnings (that was the symptom from the previous implementation).
+
+- [ ] **Step 9: Stop the demo**
+
+Press Ctrl-C in the terminal running `make dev-demo`. The cleanup hook stops the server cleanly.
+
+- [ ] **Step 10: Take note of any visual issues**
+
+If anything looks off (visual jump on release, jitter during drag, missing handles, unexpected behavior), make a note. These should not be present, but if they are, fix in a follow-up commit before continuing to Task 11.
+
+No commit for this task — it's verification only.
+
+---
+
+## Task 11: Add contributor checklist
+
+**Files:**
+- Create: `docs/dashboard-widget-checklist.md`
+
+A short reference for anyone adding a new widget type. Lives at repo root level under `docs/` (alongside `ENV.md`, project-level docs).
+
+- [ ] **Step 1: Create the file**
+
+```markdown
+# Adding a New Dashboard Widget
+
+This checklist captures the steps to add a new widget type to the dashboard.
+
+## Required
+1. **`apps/web/src/lib/widget-types.ts`** — add a `WidgetTypeDefinition` entry. The `sizing` field is required (TypeScript will fail to compile if you omit it).
+2. **`apps/web/src/components/dashboard/widget-renderer.tsx`** — add a `switch` case for the new `widget_type`.
+3. **`apps/web/src/components/dashboard/widget-picker.tsx`** — register the picker entry (icon + i18n label key).
+4. **`apps/web/src/components/dashboard/widget-config-dialog.tsx`** — add a config form if the widget needs configuration.
+5. **`apps/web/src/locales/{en,zh}/dashboard.json`** — i18n strings for the picker entry and any in-widget text.
+
+## Optional
+- Widget component: `apps/web/src/components/dashboard/widgets/<name>.tsx`
+- Vitest coverage: `apps/web/src/components/dashboard/widgets/<name>.test.tsx`
+
+## Picking a `sizing` strategy
+
+| When the widget is …                                  | Use                                              |
+| ----------------------------------------------------- | ------------------------------------------------ |
+| A chart, table, or generic free-sized panel           | `{ kind: 'free' }`                               |
+| A single fixed-size readout (one viable footprint)    | `{ kind: 'fixed' }` (set minW=maxW, minH=maxH)   |
+| A radial / gauge / aspect-locked visual               | `{ kind: 'aspect-square', tiers: [...] }`        |
+| A list/table that should hug its measured content     | `{ kind: 'content-height' }`                     |
+
+For `aspect-square`, `tiers` is the list of legal coarse-grid sizes (w × w). For gauge today: `[2, 3, 4, 5, 6]` — every integer between minW (2) and maxW (6).
+
+## Related
+
+- Architecture: `docs/superpowers/specs/2026-05-28-dashboard-widget-sizing-strategy-design.md`
+- Strategy dispatcher: `apps/web/src/components/dashboard/sizing-strategies/`
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add docs/dashboard-widget-checklist.md
+git commit -m "docs: add new-widget contributor checklist"
+```
+
+---
+
+## Task 12: Add manual verification checklist
+
+**Files:**
+- Create: `tests/manual/dashboard-widget-sizing.md`
+
+The project keeps manual verification scripts in `tests/manual/`. This one documents what to check whenever the sizing/dispatcher logic changes.
+
+- [ ] **Step 1: Verify `tests/manual/` exists**
+
+Run: `ls tests/manual | head -5`
+Expected: a list of existing manual test files. If the directory doesn't exist, run `mkdir -p tests/manual`.
+
+- [ ] **Step 2: Create the file**
+
+```markdown
+# Dashboard Widget Sizing — Manual Verification
+
+Run this checklist after touching `apps/web/src/components/dashboard/dashboard-grid.tsx`,
+`apps/web/src/components/dashboard/dashboard-layout.ts`, or anything in
+`apps/web/src/components/dashboard/sizing-strategies/`.
+
+## Setup
+
+Run `make dev-demo` (admin/admin123). Open the printed URL.
+
+## Aspect-square (gauge)
+
+- [ ] On page load (no interaction), gauge cells are visually pixel-square (1:1).
+- [ ] In edit mode, the gauge's SE handle is visible. No other handles.
+- [ ] Dragging the SE handle keeps the cell visually pixel-square throughout. Cell follows whichever cursor axis (x or y) moved more.
+- [ ] Releasing snaps the cell to the nearest tier in `[2, 3, 4, 5, 6]` (coarse grid units).
+- [ ] After resizing and reloading the page, the gauge is at the same tier — persistence works.
+- [ ] Window resize / sidebar toggle: gauge scales visually but `grid_w` doesn't change.
+- [ ] Two adjacent gauges: dragging into the neighbor blocks growth (existing collision behavior).
+
+## Content-height (top-n)
+
+- [ ] In edit mode, only the east (`e`) handle is visible on Top-N.
+- [ ] Width is resizable; height tracks content measurement.
+
+## Fixed (stat-number)
+
+- [ ] No resize handles on Stat Number widgets in edit mode.
+
+## Free (line-chart, multi-line, traffic-bar, disk-io, alert-list, server-cards, metric-card, …)
+
+- [ ] All 8 handles visible in edit mode.
+- [ ] Resize works smoothly.
+- [ ] Released height is a clean coarse multiple — no fractional pixel offsets.
+
+## Regression checks
+
+- [ ] Browser console has no errors (especially no "Maximum update depth exceeded").
+- [ ] Layout doesn't jitter or flicker during drag/resize.
+- [ ] Layout doesn't shift visibly on release of a resize that didn't change size.
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add tests/manual/dashboard-widget-sizing.md
+git commit -m "docs: add manual verification checklist for widget sizing"
+```
+
+---
+
+## Task 13: Final cleanup pass
+
+**Files:**
+- None expected to change.
+
+Sweep for leftover dead code or stale comments missed by the refactor.
+
+- [ ] **Step 1: Search for stale identifiers**
+
+Run: `grep -rn "SQUARE_TYPES\|AUTO_HEIGHT_TYPES\|visualSquareHFine\|squareIdSet\|autoIdSet\|interactionStateRef" apps/web/src docs/ --include="*.ts" --include="*.tsx"`
+Expected: matches only in the spec (`docs/superpowers/specs/2026-05-28-dashboard-widget-sizing-strategy-design.md`) describing the deletion. No runtime code references.
+
+If any other matches appear, remove them.
+
+- [ ] **Step 2: Run full typecheck + tests + lint**
+
+Run: `bun run typecheck && cd apps/web && bun run test && cd ../.. && bun x ultracite check`
+Expected: all pass.
+
+- [ ] **Step 3: Verify no commit hooks complain**
+
+Run: `git status`
+Expected: clean (no remaining modifications).
+
+- [ ] **Step 4: Stop the brainstorm server if still running**
+
+Run: `ls .superpowers/brainstorm/ 2>/dev/null && bash /Users/zingerbee/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.7/skills/brainstorming/scripts/stop-server.sh $(ls -d .superpowers/brainstorm/*/ | head -1) 2>/dev/null || echo 'no brainstorm server running'`
+Expected: either stops cleanly or "no brainstorm server running".
+
+No additional commit for this task.
+
+---
+
+## Done
+
+The full sequence (Tasks 1–13) produces:
+
+- Explicit `sizing` field on every widget type (Task 2).
+- Two-layer strategy infrastructure with unit tests (Tasks 3–7).
+- Layered behavior in `widgetsToLayout` (Task 8) and `dashboard-grid.tsx` (Task 9).
+- Manual verification done in a real browser (Task 10).
+- Contributor docs and manual checklist (Tasks 11–12).
+- Cleanup pass (Task 13).
+
+Commits along the way produce a clean history where each step is reviewable.

From 379edb5a068976155ce937356f669ae44bafb855 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 01:49:33 +0800
Subject: [PATCH 08/18] refactor(web): extract dashboard grid constants for
 sharing

---
 apps/web/src/components/dashboard/dashboard-grid.tsx | 10 +---------
 apps/web/src/components/dashboard/grid-constants.ts  | 11 +++++++++++
 2 files changed, 12 insertions(+), 9 deletions(-)
 create mode 100644 apps/web/src/components/dashboard/grid-constants.ts

diff --git a/apps/web/src/components/dashboard/dashboard-grid.tsx b/apps/web/src/components/dashboard/dashboard-grid.tsx
index 6a10d2c7..7777bde7 100644
--- a/apps/web/src/components/dashboard/dashboard-grid.tsx
+++ b/apps/web/src/components/dashboard/dashboard-grid.tsx
@@ -22,6 +22,7 @@ import type { ServerMetrics } from '@/hooks/use-servers-ws'
 import { cn } from '@/lib/utils'
 import type { DashboardWidget } from '@/lib/widget-types'
 import { layoutToPatch, widgetsToLayout } from './dashboard-layout'
+import { COLS, MARGIN, MARGIN_Y, ROW_HEIGHT, SCALE } from './grid-constants'
 import { VisibilityGate } from './visibility-gate'
 import { WidgetRenderer } from './widget-renderer'
 
@@ -43,15 +44,6 @@ function isWidgetStatic(configJson: string): boolean {
   }
 }
 
-const COLS = 12
-// Vertical fine-grain factor: persisted (coarse) grid rows are split into SCALE
-// finer rows so content-sized widgets quantize to ~ROW_HEIGHT px instead of a
-// whole coarse row. Invariant for pixel-identical legacy widgets: the legacy
-// per-row step (80 + 16) must equal SCALE * (ROW_HEIGHT + MARGIN_Y) → 4*(8+16)=96.
-const SCALE = 4
-const ROW_HEIGHT = 8
-const MARGIN: [number, number] = [16, 16]
-const MARGIN_Y = MARGIN[1]
 // Legacy coarse row pixel height, used only for the mobile single-column min-height.
 const MOBILE_ROW_PX = 80
 const MOBILE_BREAKPOINT = 768
diff --git a/apps/web/src/components/dashboard/grid-constants.ts b/apps/web/src/components/dashboard/grid-constants.ts
new file mode 100644
index 00000000..fe24ea96
--- /dev/null
+++ b/apps/web/src/components/dashboard/grid-constants.ts
@@ -0,0 +1,11 @@
+// Grid layout primitives shared between dashboard-grid.tsx and sizing-strategies/.
+// Persisted (coarse) grid rows are split into SCALE finer rows so content-sized
+// widgets quantize to ~ROW_HEIGHT px instead of a whole coarse row.
+// Invariant for pixel-identical legacy widgets: legacy per-row step
+// (80 + 16) must equal SCALE * (ROW_HEIGHT + MARGIN_Y) → 4 * (8 + 16) = 96.
+export const COLS = 12
+export const SCALE = 4
+export const ROW_HEIGHT = 8
+export const MARGIN: readonly [number, number] = [16, 16]
+export const MARGIN_X = MARGIN[0]
+export const MARGIN_Y = MARGIN[1]

From 24055e0dca33f20bf204d853e8e0a78d45e661a0 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 01:53:42 +0800
Subject: [PATCH 09/18] feat(web): declare sizing strategy on every widget type

---
 apps/web/src/lib/widget-types.ts | 85 ++++++++++++++++++++++++++------
 1 file changed, 71 insertions(+), 14 deletions(-)

diff --git a/apps/web/src/lib/widget-types.ts b/apps/web/src/lib/widget-types.ts
index e33d9c72..a23c379b 100644
--- a/apps/web/src/lib/widget-types.ts
+++ b/apps/web/src/lib/widget-types.ts
@@ -1,5 +1,11 @@
 export type WidgetCategory = 'Real-time' | 'Charts' | 'Status'
 
+export type SizingStrategy =
+  | { kind: 'free' }
+  | { kind: 'fixed' }
+  | { kind: 'aspect-square'; tiers: readonly number[] }
+  | { kind: 'content-height' }
+
 export interface WidgetTypeDefinition {
   category: WidgetCategory
   defaultH: number
@@ -10,6 +16,7 @@ export interface WidgetTypeDefinition {
   maxW?: number
   minH: number
   minW: number
+  sizing: SizingStrategy
 }
 
 export const WIDGET_TYPES = [
@@ -22,7 +29,8 @@ export const WIDGET_TYPES = [
     minW: 2,
     minH: 1,
     maxW: 2,
-    maxH: 1
+    maxH: 1,
+    sizing: { kind: 'fixed' }
   },
   {
     id: 'metric-card',
@@ -33,10 +41,31 @@ export const WIDGET_TYPES = [
     minW: 3,
     minH: 3,
     maxW: 6,
-    maxH: 6
+    maxH: 6,
+    sizing: { kind: 'free' }
+  },
+  {
+    id: 'server-cards',
+    label: 'Server Cards',
+    category: 'Real-time',
+    defaultW: 12,
+    defaultH: 6,
+    minW: 4,
+    minH: 3,
+    sizing: { kind: 'free' }
+  },
+  {
+    id: 'gauge',
+    label: 'Gauge',
+    category: 'Real-time',
+    defaultW: 2,
+    defaultH: 2,
+    minW: 2,
+    minH: 2,
+    maxW: 6,
+    maxH: 6,
+    sizing: { kind: 'aspect-square', tiers: [2, 3, 4, 5, 6] }
   },
-  { id: 'server-cards', label: 'Server Cards', category: 'Real-time', defaultW: 12, defaultH: 6, minW: 4, minH: 3 },
-  { id: 'gauge', label: 'Gauge', category: 'Real-time', defaultW: 2, defaultH: 2, minW: 2, minH: 2, maxW: 6, maxH: 6 },
   {
     id: 'line-chart',
     label: 'Line Chart',
@@ -46,7 +75,8 @@ export const WIDGET_TYPES = [
     minW: 4,
     minH: 3,
     maxW: 12,
-    maxH: 8
+    maxH: 8,
+    sizing: { kind: 'free' }
   },
   {
     id: 'multi-line',
@@ -57,9 +87,21 @@ export const WIDGET_TYPES = [
     minW: 4,
     minH: 3,
     maxW: 12,
-    maxH: 8
+    maxH: 8,
+    sizing: { kind: 'free' }
+  },
+  {
+    id: 'top-n',
+    label: 'Top N',
+    category: 'Real-time',
+    defaultW: 4,
+    defaultH: 2,
+    minW: 3,
+    minH: 2,
+    maxW: 6,
+    maxH: 8,
+    sizing: { kind: 'content-height' }
   },
-  { id: 'top-n', label: 'Top N', category: 'Real-time', defaultW: 4, defaultH: 2, minW: 3, minH: 2, maxW: 6, maxH: 8 },
   {
     id: 'alert-list',
     label: 'Alert List',
@@ -69,7 +111,8 @@ export const WIDGET_TYPES = [
     minW: 3,
     minH: 2,
     maxW: 8,
-    maxH: 8
+    maxH: 8,
+    sizing: { kind: 'free' }
   },
   {
     id: 'service-status',
@@ -80,7 +123,8 @@ export const WIDGET_TYPES = [
     minW: 3,
     minH: 2,
     maxW: 12,
-    maxH: 6
+    maxH: 6,
+    sizing: { kind: 'free' }
   },
   {
     id: 'traffic-bar',
@@ -91,7 +135,8 @@ export const WIDGET_TYPES = [
     minW: 4,
     minH: 3,
     maxW: 12,
-    maxH: 8
+    maxH: 8,
+    sizing: { kind: 'free' }
   },
   {
     id: 'disk-io',
@@ -102,7 +147,8 @@ export const WIDGET_TYPES = [
     minW: 4,
     minH: 3,
     maxW: 12,
-    maxH: 8
+    maxH: 8,
+    sizing: { kind: 'free' }
   },
   {
     id: 'server-map',
@@ -113,9 +159,19 @@ export const WIDGET_TYPES = [
     minW: 4,
     minH: 3,
     maxW: 12,
-    maxH: 8
+    maxH: 8,
+    sizing: { kind: 'free' }
+  },
+  {
+    id: 'markdown',
+    label: 'Markdown',
+    category: 'Status',
+    defaultW: 4,
+    defaultH: 3,
+    minW: 2,
+    minH: 2,
+    sizing: { kind: 'free' }
   },
-  { id: 'markdown', label: 'Markdown', category: 'Status', defaultW: 4, defaultH: 3, minW: 2, minH: 2 },
   {
     id: 'uptime-timeline',
     label: 'Uptime Timeline',
@@ -125,7 +181,8 @@ export const WIDGET_TYPES = [
     minW: 4,
     minH: 2,
     maxW: 12,
-    maxH: 6
+    maxH: 6,
+    sizing: { kind: 'free' }
   }
 ] as const satisfies readonly WidgetTypeDefinition[]
 

From 12f0b674af9a127318f6a7cb9df9690bdccf7a18 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 01:55:52 +0800
Subject: [PATCH 10/18] feat(web): add nearestTier helper for sizing strategies

---
 .../dashboard/sizing-strategies/index.test.ts | 32 +++++++++++++++++++
 .../dashboard/sizing-strategies/index.ts      |  5 +++
 2 files changed, 37 insertions(+)
 create mode 100644 apps/web/src/components/dashboard/sizing-strategies/index.test.ts
 create mode 100644 apps/web/src/components/dashboard/sizing-strategies/index.ts

diff --git a/apps/web/src/components/dashboard/sizing-strategies/index.test.ts b/apps/web/src/components/dashboard/sizing-strategies/index.test.ts
new file mode 100644
index 00000000..c27f0c43
--- /dev/null
+++ b/apps/web/src/components/dashboard/sizing-strategies/index.test.ts
@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest'
+import { nearestTier } from './index'
+
+describe('nearestTier', () => {
+  const tiers = [2, 3, 4, 5, 6] as const
+
+  it('returns the exact tier when value matches', () => {
+    expect(nearestTier(3, tiers)).toBe(3)
+  })
+
+  it('rounds down when between two tiers, closer to lower', () => {
+    expect(nearestTier(3.4, tiers)).toBe(3)
+  })
+
+  it('rounds up when between two tiers, closer to upper', () => {
+    expect(nearestTier(3.6, tiers)).toBe(4)
+  })
+
+  it('picks the first tier on exact ties (conservative)', () => {
+    expect(nearestTier(3.5, [3, 4])).toBe(3)
+    expect(nearestTier(4.5, tiers)).toBe(4)
+  })
+
+  it('clamps to minimum tier for values below the range', () => {
+    expect(nearestTier(0, tiers)).toBe(2)
+    expect(nearestTier(-5, tiers)).toBe(2)
+  })
+
+  it('clamps to maximum tier for values above the range', () => {
+    expect(nearestTier(100, tiers)).toBe(6)
+  })
+})
diff --git a/apps/web/src/components/dashboard/sizing-strategies/index.ts b/apps/web/src/components/dashboard/sizing-strategies/index.ts
new file mode 100644
index 00000000..aab68bdc
--- /dev/null
+++ b/apps/web/src/components/dashboard/sizing-strategies/index.ts
@@ -0,0 +1,5 @@
+// Returns the tier closest to `value`. Ties pick the first (smaller) tier —
+// conservative bias avoids accidental upgrades when the user releases mid-drag.
+export function nearestTier(value: number, tiers: readonly number[]): number {
+  return tiers.reduce((best, t) => (Math.abs(t - value) < Math.abs(best - value) ? t : best), tiers[0])
+}

From 25691d3e5810fbc11eec3cdcd6c03d82a6c46aa0 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 01:57:15 +0800
Subject: [PATCH 11/18] feat(web): add applyCoarsePatch helper for sizing
 strategies

---
 .../dashboard/sizing-strategies/index.test.ts | 47 ++++++++++++++++++-
 .../dashboard/sizing-strategies/index.ts      | 18 +++++++
 2 files changed, 64 insertions(+), 1 deletion(-)

diff --git a/apps/web/src/components/dashboard/sizing-strategies/index.test.ts b/apps/web/src/components/dashboard/sizing-strategies/index.test.ts
index c27f0c43..b363c581 100644
--- a/apps/web/src/components/dashboard/sizing-strategies/index.test.ts
+++ b/apps/web/src/components/dashboard/sizing-strategies/index.test.ts
@@ -1,5 +1,6 @@
+import type { LayoutItem } from 'react-grid-layout'
 import { describe, expect, it } from 'vitest'
-import { nearestTier } from './index'
+import { applyCoarsePatch, nearestTier, type SnapPatch } from './index'
 
 describe('nearestTier', () => {
   const tiers = [2, 3, 4, 5, 6] as const
@@ -30,3 +31,47 @@ describe('nearestTier', () => {
     expect(nearestTier(100, tiers)).toBe(6)
   })
 })
+
+describe('applyCoarsePatch', () => {
+  const baseItem: LayoutItem = {
+    i: 'gauge-1',
+    x: 2,
+    y: 0,
+    w: 2,
+    h: 8 // fine units (= 2 coarse)
+  }
+
+  it('returns item unchanged when patch is empty', () => {
+    const result = applyCoarsePatch(baseItem, {})
+    expect(result.w).toBe(2)
+    expect(result.h).toBe(8)
+  })
+
+  it('applies coarse w directly (w lives in coarse units throughout)', () => {
+    const patch: SnapPatch = { w: 3 }
+    const result = applyCoarsePatch(baseItem, patch)
+    expect(result.w).toBe(3)
+    expect(result.h).toBe(8) // unchanged
+  })
+
+  it('converts coarse h to fine by multiplying by SCALE (4)', () => {
+    const patch: SnapPatch = { h: 3 }
+    const result = applyCoarsePatch(baseItem, patch)
+    expect(result.w).toBe(2)
+    expect(result.h).toBe(12) // 3 * 4 = 12 fine
+  })
+
+  it('applies both w and h', () => {
+    const patch: SnapPatch = { w: 4, h: 4 }
+    const result = applyCoarsePatch(baseItem, patch)
+    expect(result.w).toBe(4)
+    expect(result.h).toBe(16)
+  })
+
+  it('does not mutate the input item', () => {
+    const patch: SnapPatch = { w: 5, h: 5 }
+    applyCoarsePatch(baseItem, patch)
+    expect(baseItem.w).toBe(2)
+    expect(baseItem.h).toBe(8)
+  })
+})
diff --git a/apps/web/src/components/dashboard/sizing-strategies/index.ts b/apps/web/src/components/dashboard/sizing-strategies/index.ts
index aab68bdc..14063ce5 100644
--- a/apps/web/src/components/dashboard/sizing-strategies/index.ts
+++ b/apps/web/src/components/dashboard/sizing-strategies/index.ts
@@ -1,5 +1,23 @@
+import type { LayoutItem } from 'react-grid-layout'
+import { SCALE } from '../grid-constants'
+
 // Returns the tier closest to `value`. Ties pick the first (smaller) tier —
 // conservative bias avoids accidental upgrades when the user releases mid-drag.
 export function nearestTier(value: number, tiers: readonly number[]): number {
   return tiers.reduce((best, t) => (Math.abs(t - value) < Math.abs(best - value) ? t : best), tiers[0])
 }
+
+// A coarse-unit override returned by `snapOnRelease`. The grid layer applies
+// it to fine-unit layout items via `applyCoarsePatch`.
+export interface SnapPatch {
+  h?: number // coarse units (will be multiplied by SCALE when applied)
+  w?: number // coarse units
+}
+
+export function applyCoarsePatch(item: LayoutItem, patch: SnapPatch): LayoutItem {
+  return {
+    ...item,
+    w: patch.w ?? item.w,
+    h: patch.h !== undefined ? patch.h * SCALE : item.h
+  }
+}

From ae3ed8ac16b31044b4f5278833fdf554666f5d14 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 01:59:05 +0800
Subject: [PATCH 12/18] feat(web): add normalizeRenderItem for idle widget
 sizing (layer A)

---
 .../sizing-strategies/normalize.test.ts       | 100 ++++++++++++++++++
 .../dashboard/sizing-strategies/normalize.ts  |  44 ++++++++
 2 files changed, 144 insertions(+)
 create mode 100644 apps/web/src/components/dashboard/sizing-strategies/normalize.test.ts
 create mode 100644 apps/web/src/components/dashboard/sizing-strategies/normalize.ts

diff --git a/apps/web/src/components/dashboard/sizing-strategies/normalize.test.ts b/apps/web/src/components/dashboard/sizing-strategies/normalize.test.ts
new file mode 100644
index 00000000..6c805a34
--- /dev/null
+++ b/apps/web/src/components/dashboard/sizing-strategies/normalize.test.ts
@@ -0,0 +1,100 @@
+import type { LayoutItem } from 'react-grid-layout'
+import { describe, expect, it } from 'vitest'
+import type { SizingStrategy } from '@/lib/widget-types'
+import { normalizeRenderItem, pixelSquareFineH } from './normalize'
+
+const W_AT_1004 = 1004 // a representative container width
+
+describe('pixelSquareFineH', () => {
+  it('returns wCoarse * SCALE when containerWidth is non-positive', () => {
+    expect(pixelSquareFineH(2, 0)).toBe(8)
+    expect(pixelSquareFineH(3, -100)).toBe(12)
+  })
+
+  it('returns pixel-square fine h at typical container width', () => {
+    // At 1004px: colStepPx = (1004+16)/12 = 85; fineRowStepPx = 8+16 = 24
+    // pixelSquareFineH(2) = round(2 * 85 / 24) = round(7.083) = 7
+    expect(pixelSquareFineH(2, W_AT_1004)).toBe(7)
+    // pixelSquareFineH(3) = round(3 * 85 / 24) = round(10.625) = 11
+    expect(pixelSquareFineH(3, W_AT_1004)).toBe(11)
+    // pixelSquareFineH(6) = round(6 * 85 / 24) = round(21.25) = 21
+    expect(pixelSquareFineH(6, W_AT_1004)).toBe(21)
+  })
+
+  it('never returns less than 1', () => {
+    expect(pixelSquareFineH(0, W_AT_1004)).toBe(1)
+  })
+})
+
+describe('normalizeRenderItem', () => {
+  const baseItem: LayoutItem = {
+    i: 'widget-1',
+    x: 0,
+    y: 0,
+    w: 2,
+    h: 8, // fine units
+    minW: 2,
+    minH: 8,
+    maxW: 6,
+    maxH: 24
+  }
+
+  it('returns aspect-square h derived from w', () => {
+    const strategy: SizingStrategy = { kind: 'aspect-square', tiers: [2, 3, 4, 5, 6] }
+    const result = normalizeRenderItem(baseItem, strategy, { containerWidth: W_AT_1004 })
+    expect(result.h).toBe(7) // pixelSquareFineH(2, 1004)
+    expect(result.minH).toBe(7) // pixelSquareFineH(minW=2, 1004)
+    expect(result.maxH).toBe(21) // pixelSquareFineH(maxW=6, 1004)
+  })
+
+  it('aspect-square leaves w/x/y/minW/maxW unchanged', () => {
+    const strategy: SizingStrategy = { kind: 'aspect-square', tiers: [2, 3, 4, 5, 6] }
+    const result = normalizeRenderItem(baseItem, strategy, { containerWidth: W_AT_1004 })
+    expect(result.w).toBe(2)
+    expect(result.x).toBe(0)
+    expect(result.minW).toBe(2)
+    expect(result.maxW).toBe(6)
+  })
+
+  it('content-height uses measured fine h when present', () => {
+    const strategy: SizingStrategy = { kind: 'content-height' }
+    const result = normalizeRenderItem(baseItem, strategy, {
+      containerWidth: W_AT_1004,
+      autoMeasuredFineH: 11
+    })
+    expect(result.h).toBe(11)
+    expect(result.minH).toBe(11)
+    expect(result.maxH).toBe(11)
+  })
+
+  it('content-height returns item unchanged when measurement is missing', () => {
+    const strategy: SizingStrategy = { kind: 'content-height' }
+    const result = normalizeRenderItem(baseItem, strategy, { containerWidth: W_AT_1004 })
+    expect(result.h).toBe(8) // unchanged
+    expect(result.minH).toBe(8)
+    expect(result.maxH).toBe(24)
+  })
+
+  it('free returns item unchanged', () => {
+    const strategy: SizingStrategy = { kind: 'free' }
+    const result = normalizeRenderItem(baseItem, strategy, { containerWidth: W_AT_1004 })
+    expect(result.h).toBe(8)
+    expect(result.minH).toBe(8)
+    expect(result.maxH).toBe(24)
+  })
+
+  it('fixed returns item unchanged', () => {
+    const strategy: SizingStrategy = { kind: 'fixed' }
+    const result = normalizeRenderItem(baseItem, strategy, { containerWidth: W_AT_1004 })
+    expect(result.h).toBe(8)
+    expect(result.minH).toBe(8)
+    expect(result.maxH).toBe(24)
+  })
+
+  it('aspect-square handles undefined maxW gracefully', () => {
+    const strategy: SizingStrategy = { kind: 'aspect-square', tiers: [2, 3, 4, 5, 6] }
+    const itemNoMaxW: LayoutItem = { ...baseItem, maxW: undefined, maxH: undefined }
+    const result = normalizeRenderItem(itemNoMaxW, strategy, { containerWidth: W_AT_1004 })
+    expect(result.maxH).toBeUndefined()
+  })
+})
diff --git a/apps/web/src/components/dashboard/sizing-strategies/normalize.ts b/apps/web/src/components/dashboard/sizing-strategies/normalize.ts
new file mode 100644
index 00000000..17cb4103
--- /dev/null
+++ b/apps/web/src/components/dashboard/sizing-strategies/normalize.ts
@@ -0,0 +1,44 @@
+import type { LayoutItem } from 'react-grid-layout'
+import type { SizingStrategy } from '@/lib/widget-types'
+import { COLS, MARGIN_X, MARGIN_Y, ROW_HEIGHT, SCALE } from '../grid-constants'
+
+export interface NormalizeContext {
+  autoMeasuredFineH?: number // populated for content-height widgets via ResizeObserver
+  containerWidth: number
+}
+
+// Same formula RGL's aspectRatio(1) uses internally (see
+// react-grid-layout@2.2.2 internals). Replicated here so we can
+// apply it at idle render time — RGL constraints only run during resize.
+export function pixelSquareFineH(wCoarse: number, containerWidth: number): number {
+  if (containerWidth <= 0) {
+    return wCoarse * SCALE
+  }
+  const colStepPx = (containerWidth + MARGIN_X) / COLS
+  const fineRowStepPx = ROW_HEIGHT + MARGIN_Y
+  return Math.max(1, Math.round((wCoarse * colStepPx) / fineRowStepPx))
+}
+
+// Applies strategy-specific overrides to a fine-unit layout item.
+// Operates entirely in fine units (caller has already done `h *= SCALE`).
+// Returns a NEW item — never mutates the input.
+export function normalizeRenderItem(item: LayoutItem, strategy: SizingStrategy, ctx: NormalizeContext): LayoutItem {
+  switch (strategy.kind) {
+    case 'aspect-square': {
+      const h = pixelSquareFineH(item.w, ctx.containerWidth)
+      const minH = pixelSquareFineH(item.minW ?? 2, ctx.containerWidth)
+      const maxH = item.maxW !== undefined ? pixelSquareFineH(item.maxW, ctx.containerWidth) : undefined
+      return { ...item, h, minH, maxH }
+    }
+    case 'content-height': {
+      const measured = ctx.autoMeasuredFineH
+      if (measured !== undefined) {
+        return { ...item, h: measured, minH: measured, maxH: measured }
+      }
+      return item
+    }
+    case 'fixed':
+    case 'free':
+      return item
+  }
+}

From 1fff597e3c1bf21b9e049da1d1288de85aa431f5 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 02:01:07 +0800
Subject: [PATCH 13/18] feat(web): add applyStrategy with RGL constraints
 (layer B)

---
 .../dashboard/sizing-strategies/index.test.ts | 63 ++++++++++++++++++-
 .../dashboard/sizing-strategies/index.ts      | 42 +++++++++++++
 2 files changed, 104 insertions(+), 1 deletion(-)

diff --git a/apps/web/src/components/dashboard/sizing-strategies/index.test.ts b/apps/web/src/components/dashboard/sizing-strategies/index.test.ts
index b363c581..52f8cba1 100644
--- a/apps/web/src/components/dashboard/sizing-strategies/index.test.ts
+++ b/apps/web/src/components/dashboard/sizing-strategies/index.test.ts
@@ -1,6 +1,7 @@
 import type { LayoutItem } from 'react-grid-layout'
 import { describe, expect, it } from 'vitest'
-import { applyCoarsePatch, nearestTier, type SnapPatch } from './index'
+import type { SizingStrategy } from '@/lib/widget-types'
+import { applyCoarsePatch, applyStrategy, nearestTier, type SnapPatch } from './index'
 
 describe('nearestTier', () => {
   const tiers = [2, 3, 4, 5, 6] as const
@@ -75,3 +76,63 @@ describe('applyCoarsePatch', () => {
     expect(baseItem.h).toBe(8)
   })
 })
+
+describe('applyStrategy', () => {
+  it('free returns no constraints and undefined resize handles', () => {
+    const strategy: SizingStrategy = { kind: 'free' }
+    const desc = applyStrategy(strategy)
+    expect(desc.constraints).toEqual([])
+    expect(desc.resizeHandles).toBeUndefined()
+    expect(desc.isResizable).toBe(true)
+  })
+
+  it('fixed returns no constraints, empty resize handles, isResizable false', () => {
+    const strategy: SizingStrategy = { kind: 'fixed' }
+    const desc = applyStrategy(strategy)
+    expect(desc.constraints).toEqual([])
+    expect(desc.resizeHandles).toEqual([])
+    expect(desc.isResizable).toBe(false)
+  })
+
+  it('aspect-square returns aspectRatio(1) constraint and SE handle', () => {
+    const strategy: SizingStrategy = { kind: 'aspect-square', tiers: [2, 3, 4, 5, 6] }
+    const desc = applyStrategy(strategy)
+    expect(desc.constraints).toHaveLength(1)
+    expect(desc.constraints[0].name).toBe('aspectRatio(1)')
+    expect(desc.resizeHandles).toEqual(['se'])
+    expect(desc.isResizable).toBe(true)
+  })
+
+  it('content-height returns lockHeight constraint when measured', () => {
+    const strategy: SizingStrategy = { kind: 'content-height' }
+    const desc = applyStrategy(strategy, 11)
+    expect(desc.constraints).toHaveLength(1)
+    expect(desc.constraints[0].name).toBe('lockHeight(11)')
+    expect(desc.resizeHandles).toEqual(['e'])
+    expect(desc.isResizable).toBe(true)
+  })
+
+  it('content-height returns no constraint when unmeasured', () => {
+    const strategy: SizingStrategy = { kind: 'content-height' }
+    const desc = applyStrategy(strategy)
+    expect(desc.constraints).toEqual([])
+    expect(desc.resizeHandles).toEqual(['e'])
+    expect(desc.isResizable).toBe(true)
+  })
+
+  it('lockHeight constraint locks h to the measured value', () => {
+    const strategy: SizingStrategy = { kind: 'content-height' }
+    const desc = applyStrategy(strategy, 11)
+    const constraint = desc.constraints[0]
+    // Call the constraint directly — params: item, w, h, handle, context
+    const result = constraint.constrainSize?.({ i: 'x', x: 0, y: 0, w: 4, h: 99 }, 4, 99, 'e', {
+      cols: 12,
+      containerWidth: 1000,
+      maxRows: Number.POSITIVE_INFINITY,
+      rowHeight: 8,
+      margin: [16, 16],
+      layout: []
+    } as any)
+    expect(result).toEqual({ w: 4, h: 11 })
+  })
+})
diff --git a/apps/web/src/components/dashboard/sizing-strategies/index.ts b/apps/web/src/components/dashboard/sizing-strategies/index.ts
index 14063ce5..4f42cadb 100644
--- a/apps/web/src/components/dashboard/sizing-strategies/index.ts
+++ b/apps/web/src/components/dashboard/sizing-strategies/index.ts
@@ -1,4 +1,7 @@
 import type { LayoutItem } from 'react-grid-layout'
+import type { LayoutConstraint, ResizeHandleAxis } from 'react-grid-layout/core'
+import { aspectRatio } from 'react-grid-layout/core'
+import type { SizingStrategy } from '@/lib/widget-types'
 import { SCALE } from '../grid-constants'
 
 // Returns the tier closest to `value`. Ties pick the first (smaller) tier —
@@ -21,3 +24,42 @@ export function applyCoarsePatch(item: LayoutItem, patch: SnapPatch): LayoutItem
     h: patch.h !== undefined ? patch.h * SCALE : item.h
   }
 }
+
+export interface StrategyDescriptor {
+  // Constraints attached to LayoutItem.constraints. Applied by RGL inside
+  // applySizeConstraints during the resize pipeline. NOT applied at idle
+  // layout sync — use `normalizeRenderItem` for idle h.
+  constraints: LayoutConstraint[]
+
+  // Whether the item participates in resize at all.
+  isResizable: boolean
+
+  // Which resize handles to render. undefined = RGL default (all 8 corners/edges).
+  resizeHandles?: ResizeHandleAxis[]
+}
+
+function lockHeight(fineH: number): LayoutConstraint {
+  return {
+    name: `lockHeight(${fineH})`,
+    constrainSize(_item, w) {
+      return { w, h: fineH }
+    }
+  }
+}
+
+export function applyStrategy(strategy: SizingStrategy, measuredFineH?: number): StrategyDescriptor {
+  switch (strategy.kind) {
+    case 'free':
+      return { constraints: [], resizeHandles: undefined, isResizable: true }
+    case 'fixed':
+      return { constraints: [], resizeHandles: [], isResizable: false }
+    case 'aspect-square':
+      return { constraints: [aspectRatio(1)], resizeHandles: ['se'], isResizable: true }
+    case 'content-height':
+      return {
+        constraints: measuredFineH !== undefined ? [lockHeight(measuredFineH)] : [],
+        resizeHandles: ['e'],
+        isResizable: true
+      }
+  }
+}

From b8b16301a83309a1a4cd85f0bb0374ebf39c3886 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 02:02:17 +0800
Subject: [PATCH 14/18] feat(web): add snapOnRelease for aspect-square tier
 snap

---
 .../dashboard/sizing-strategies/index.test.ts | 41 +++++++++++++++++++
 .../dashboard/sizing-strategies/index.ts      | 17 ++++++++
 2 files changed, 58 insertions(+)

diff --git a/apps/web/src/components/dashboard/sizing-strategies/index.test.ts b/apps/web/src/components/dashboard/sizing-strategies/index.test.ts
index 52f8cba1..16268a2a 100644
--- a/apps/web/src/components/dashboard/sizing-strategies/index.test.ts
+++ b/apps/web/src/components/dashboard/sizing-strategies/index.test.ts
@@ -136,3 +136,44 @@ describe('applyStrategy', () => {
     expect(result).toEqual({ w: 4, h: 11 })
   })
 })
+
+import { snapOnRelease } from './index'
+
+describe('snapOnRelease', () => {
+  const baseItem: LayoutItem = {
+    i: 'gauge-1',
+    x: 0,
+    y: 0,
+    w: 3,
+    h: 11 // fine units
+  }
+
+  it('aspect-square snaps w to the nearest tier and returns coarse h = w', () => {
+    const strategy: SizingStrategy = { kind: 'aspect-square', tiers: [2, 3, 4, 5, 6] }
+    const result = snapOnRelease({ ...baseItem, w: 4 }, strategy, { containerWidth: 1004 })
+    expect(result).toEqual({ w: 4, h: 4 })
+  })
+
+  it('aspect-square snaps non-tier w to nearest', () => {
+    const strategy: SizingStrategy = { kind: 'aspect-square', tiers: [2, 3, 4, 5, 6] }
+    // base.w shouldn't be fractional in practice, but commitLayoutChange
+    // may receive a w just above a tier boundary during dragging — verify snap.
+    const result = snapOnRelease({ ...baseItem, w: 3 }, strategy, { containerWidth: 1004 })
+    expect(result).toEqual({ w: 3, h: 3 })
+  })
+
+  it('free returns empty patch', () => {
+    const strategy: SizingStrategy = { kind: 'free' }
+    expect(snapOnRelease(baseItem, strategy, { containerWidth: 1004 })).toEqual({})
+  })
+
+  it('fixed returns empty patch', () => {
+    const strategy: SizingStrategy = { kind: 'fixed' }
+    expect(snapOnRelease(baseItem, strategy, { containerWidth: 1004 })).toEqual({})
+  })
+
+  it('content-height returns empty patch', () => {
+    const strategy: SizingStrategy = { kind: 'content-height' }
+    expect(snapOnRelease(baseItem, strategy, { containerWidth: 1004 })).toEqual({})
+  })
+})
diff --git a/apps/web/src/components/dashboard/sizing-strategies/index.ts b/apps/web/src/components/dashboard/sizing-strategies/index.ts
index 4f42cadb..7d379b17 100644
--- a/apps/web/src/components/dashboard/sizing-strategies/index.ts
+++ b/apps/web/src/components/dashboard/sizing-strategies/index.ts
@@ -47,6 +47,23 @@ function lockHeight(fineH: number): LayoutConstraint {
   }
 }
 
+export interface SnapContext {
+  containerWidth: number
+}
+
+export function snapOnRelease(item: LayoutItem, strategy: SizingStrategy, _ctx: SnapContext): SnapPatch {
+  switch (strategy.kind) {
+    case 'aspect-square': {
+      const tier = nearestTier(item.w, strategy.tiers)
+      return { w: tier, h: tier }
+    }
+    case 'free':
+    case 'fixed':
+    case 'content-height':
+      return {}
+  }
+}
+
 export function applyStrategy(strategy: SizingStrategy, measuredFineH?: number): StrategyDescriptor {
   switch (strategy.kind) {
     case 'free':

From 645a07507ae2b558996df2bcc9de6bb1097a4889 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 02:04:24 +0800
Subject: [PATCH 15/18] feat(web): snap aspect-square widgets to nearest tier
 in widgetsToLayout

---
 .../dashboard/dashboard-layout.test.ts        | 52 +++++++++++++++++++
 .../components/dashboard/dashboard-layout.ts  | 15 ++++--
 2 files changed, 64 insertions(+), 3 deletions(-)

diff --git a/apps/web/src/components/dashboard/dashboard-layout.test.ts b/apps/web/src/components/dashboard/dashboard-layout.test.ts
index e497d11e..139a3e28 100644
--- a/apps/web/src/components/dashboard/dashboard-layout.test.ts
+++ b/apps/web/src/components/dashboard/dashboard-layout.test.ts
@@ -2,6 +2,23 @@ import { describe, expect, it } from 'vitest'
 import type { DashboardWidget } from '@/lib/widget-types'
 import { layoutToPatch, mergeLayoutPatch, normalizeNewWidgetPlacement, widgetsToLayout } from './dashboard-layout'
 
+function makeWidget(overrides: Partial<DashboardWidget>): DashboardWidget {
+  return {
+    id: 'w1',
+    dashboard_id: 'd1',
+    widget_type: 'gauge',
+    grid_x: 0,
+    grid_y: 0,
+    grid_w: 2,
+    grid_h: 2,
+    sort_order: 0,
+    title: null,
+    config_json: '{}',
+    created_at: '2026-05-28T00:00:00Z',
+    ...overrides
+  }
+}
+
 const widgets: DashboardWidget[] = [
   {
     id: 'w-1',
@@ -31,6 +48,41 @@ const widgets: DashboardWidget[] = [
   }
 ]
 
+describe('widgetsToLayout', () => {
+  describe('aspect-square clamp', () => {
+    it('snaps a non-square gauge to the nearest tier (uses max of w/h)', () => {
+      // grid_w=3, grid_h=5 → max=5 → nearest tier in [2,3,4,5,6] is 5
+      const widget = makeWidget({ grid_w: 3, grid_h: 5 })
+      const [item] = widgetsToLayout([widget])
+      expect(item.w).toBe(5)
+      expect(item.h).toBe(5)
+    })
+
+    it('preserves a gauge already at a legal tier', () => {
+      const widget = makeWidget({ grid_w: 4, grid_h: 4 })
+      const [item] = widgetsToLayout([widget])
+      expect(item.w).toBe(4)
+      expect(item.h).toBe(4)
+    })
+
+    it('clamps an oversized gauge to maxW tier', () => {
+      // grid_w=10 → clamped to maxW=6 by existing logic → tier=6
+      const widget = makeWidget({ grid_w: 10, grid_h: 10 })
+      const [item] = widgetsToLayout([widget])
+      expect(item.w).toBe(6)
+      expect(item.h).toBe(6)
+    })
+
+    it('does not snap non-aspect-square widgets', () => {
+      // metric-card is free; should keep grid_w/h as-is (within min/max)
+      const widget = makeWidget({ widget_type: 'metric-card', grid_w: 4, grid_h: 3 })
+      const [item] = widgetsToLayout([widget])
+      expect(item.w).toBe(4)
+      expect(item.h).toBe(3)
+    })
+  })
+})
+
 describe('dashboard-layout', () => {
   it('widgetsToLayout adds min and max constraints from widget definitions', () => {
     const layout = widgetsToLayout(widgets)
diff --git a/apps/web/src/components/dashboard/dashboard-layout.ts b/apps/web/src/components/dashboard/dashboard-layout.ts
index f0de2424..0a9019b9 100644
--- a/apps/web/src/components/dashboard/dashboard-layout.ts
+++ b/apps/web/src/components/dashboard/dashboard-layout.ts
@@ -1,6 +1,7 @@
 import type { Layout, LayoutItem } from 'react-grid-layout'
 import type { DashboardWidget, WidgetTypeDefinition } from '@/lib/widget-types'
 import { WIDGET_TYPES } from '@/lib/widget-types'
+import { nearestTier } from './sizing-strategies'
 
 export interface LayoutPatch {
   grid_h: number
@@ -42,6 +43,17 @@ export function widgetsToLayout(widgets: DashboardWidget[]): Layout {
     if (maxH !== undefined) {
       h = Math.min(h, maxH)
     }
+
+    // Aspect-square widgets persist as w_coarse === h_coarse. If historical data
+    // somehow has them out of sync (or grid_w not at a legal tier), snap here so
+    // the cell renders square on first load. Next user drag/resize writes back.
+    const sizing = WIDGET_TYPE_MAP.get(widget.widget_type)?.sizing
+    if (sizing?.kind === 'aspect-square') {
+      const tier = nearestTier(Math.max(w, h), sizing.tiers)
+      w = tier
+      h = tier
+    }
+
     const item: LayoutItem = {
       i: widget.id,
       x: widget.grid_x,
@@ -57,9 +69,6 @@ export function widgetsToLayout(widgets: DashboardWidget[]): Layout {
     if (maxH !== undefined) {
       item.maxH = maxH
     }
-    if (maxW !== undefined && maxH !== undefined && minW === maxW && minH === maxH) {
-      item.isResizable = false
-    }
     if (isWidgetStatic(widget.config_json)) {
       item.static = true
     }

From 620123c7deb077dd5201ead60b3ccac078c2b965 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 02:08:49 +0800
Subject: [PATCH 16/18] refactor(web): route dashboard grid sizing through
 strategy dispatcher

Replace SQUARE_TYPES / AUTO_HEIGHT_TYPES / visualSquareHFine /
interactionStateRef with widgetById + getStrategy + normalizeRenderItem
(layer A, idle) + applyStrategy (layer B, RGL constraints). Per-strategy
h snap in updateLiveLayout/commitLayoutChange replaces the inline
overrides. snapOnRelease + applyCoarsePatch land aspect-square tier
snaps on resize end.
---
 .../components/dashboard/dashboard-grid.tsx   | 153 ++++++++----------
 1 file changed, 70 insertions(+), 83 deletions(-)

diff --git a/apps/web/src/components/dashboard/dashboard-grid.tsx b/apps/web/src/components/dashboard/dashboard-grid.tsx
index 7777bde7..309986dc 100644
--- a/apps/web/src/components/dashboard/dashboard-grid.tsx
+++ b/apps/web/src/components/dashboard/dashboard-grid.tsx
@@ -20,9 +20,12 @@ import 'react-grid-layout/css/styles.css'
 import { Button } from '@/components/ui/button'
 import type { ServerMetrics } from '@/hooks/use-servers-ws'
 import { cn } from '@/lib/utils'
-import type { DashboardWidget } from '@/lib/widget-types'
+import type { DashboardWidget, SizingStrategy, WidgetTypeDefinition } from '@/lib/widget-types'
+import { WIDGET_TYPES } from '@/lib/widget-types'
 import { layoutToPatch, widgetsToLayout } from './dashboard-layout'
 import { COLS, MARGIN, MARGIN_Y, ROW_HEIGHT, SCALE } from './grid-constants'
+import { applyCoarsePatch, applyStrategy, snapOnRelease } from './sizing-strategies'
+import { normalizeRenderItem } from './sizing-strategies/normalize'
 import { VisibilityGate } from './visibility-gate'
 import { WidgetRenderer } from './widget-renderer'
 
@@ -48,13 +51,7 @@ function isWidgetStatic(configJson: string): boolean {
 const MOBILE_ROW_PX = 80
 const MOBILE_BREAKPOINT = 768
 
-// Widgets whose grid cell height should follow their measured content height
-// instead of a fixed/estimated number of rows.
-const AUTO_HEIGHT_TYPES = new Set(['top-n'])
-
-// Widgets that must stay square (1:1 in coarse grid units). Width and height
-// are locked together during resize so the radial visual stays balanced.
-const SQUARE_TYPES = new Set(['gauge'])
+const WIDGET_TYPE_MAP = new Map<string, WidgetTypeDefinition>(WIDGET_TYPES.map((widget) => [widget.id, widget]))
 
 function pxToGridUnits(px: number): number {
   return Math.max(2, Math.ceil((px + MARGIN_Y) / (ROW_HEIGHT + MARGIN_Y)))
@@ -181,26 +178,18 @@ export function DashboardGrid({
     setAutoUnits((prev) => (prev[id] === units ? prev : { ...prev, [id]: units }))
   }, [])
 
-  const squareIdSet = useMemo(
-    () => new Set(widgets.filter((w) => SQUARE_TYPES.has(w.widget_type)).map((w) => w.id)),
-    [widgets]
-  )
+  const widgetById = useMemo(() => new Map(widgets.map((w) => [w.id, w])), [widgets])
 
-  // Square widgets persist as `w_coarse === h_coarse`, but coarse rows are
-  // taller than columns (96px vs ~85px), so the rendered cell is rectangular.
-  // Override the render height in fine units so the cell is pixel-square. The
-  // persisted coarse height is left untouched — only the rendered height
-  // changes, and a drag commit re-derives both from `w`.
-  const visualSquareHFine = useCallback(
-    (wCoarse: number): number => {
-      if (width <= 0) {
-        return wCoarse * SCALE
+  const getStrategy = useCallback(
+    (itemId: string): SizingStrategy => {
+      const widget = widgetById.get(itemId)
+      if (!widget) {
+        return { kind: 'free' }
       }
-      const colStepPx = (width + MARGIN[0]) / COLS
-      const fineRowStepPx = ROW_HEIGHT + MARGIN_Y
-      return Math.max(1, Math.round((wCoarse * colStepPx) / fineRowStepPx))
+      const def = WIDGET_TYPE_MAP.get(widget.widget_type)
+      return def?.sizing ?? { kind: 'free' }
     },
-    [width]
+    [widgetById]
   )
 
   // Persisted grid units are coarse (1 row == ROW_HEIGHT*SCALE px). The grid
@@ -218,38 +207,36 @@ export function DashboardGrid({
       if (item.maxH !== undefined) {
         item.maxH *= SCALE
       }
-      const units = autoUnits[item.i]
-      if (units !== undefined) {
-        // Auto-height widgets fit their content exactly: height is locked to the
-        // measured content and cannot be adjusted. Only horizontal resize stays.
-        item.minH = units
-        item.maxH = units
-        item.h = units
-        item.resizeHandles = ['e']
+
+      const strategy = getStrategy(item.i)
+      const measured = autoUnits[item.i]
+
+      // Layer A: idle h / minH / maxH per strategy.
+      const normalized = normalizeRenderItem(item, strategy, {
+        containerWidth: width,
+        autoMeasuredFineH: measured
+      })
+      item.h = normalized.h
+      item.minH = normalized.minH
+      item.maxH = normalized.maxH
+
+      // Layer B: resize-time constraints, handles, resizability.
+      const desc = applyStrategy(strategy, measured)
+      if (desc.constraints.length > 0) {
+        item.constraints = desc.constraints
+      }
+      if (desc.resizeHandles) {
+        item.resizeHandles = desc.resizeHandles
       }
-      if (squareIdSet.has(item.i)) {
-        // Square widgets resize via the SE corner so the user can grow by
-        // dragging either edge of the cell. Idle h is the pixel-square value
-        // (visualSquareHFine); minH/maxH are also derived so RGL doesn't clamp
-        // h back to the un-overridden coarse-fine value.
-        item.resizeHandles = ['se']
-        item.h = visualSquareHFine(item.w)
-        const minW = item.minW ?? 2
-        const maxW = item.maxW
-        item.minH = visualSquareHFine(minW)
-        item.maxH = maxW !== undefined ? visualSquareHFine(maxW) : undefined
+      if (!desc.isResizable) {
+        item.isResizable = false
       }
     }
     return deoverlapLayout(layout)
-  }, [widgets, autoUnits, squareIdSet, visualSquareHFine])
+  }, [widgets, autoUnits, width, getStrategy])
 
   const [liveLayout, setLiveLayout] = useState<Layout>(baseLayout)
   const [interactionState, setInteractionState] = useState<InteractionState>('idle')
-  // Mirror interactionState into a ref so updateLiveLayout's callback (called
-  // on every RGL echo) can branch on "currently resizing" without forcing a
-  // re-bind every state transition.
-  const interactionStateRef = useRef(interactionState)
-  interactionStateRef.current = interactionState
 
   // While editing (or actively dragging/resizing), freeze the servers snapshot fed
   // to widgets. Otherwise every websocket tick swaps the servers array reference
@@ -263,11 +250,6 @@ export function DashboardGrid({
   }
   const widgetServers = shouldFreeze ? frozenServersRef.current : servers
 
-  const autoIdSet = useMemo(
-    () => new Set(widgets.filter((w) => AUTO_HEIGHT_TYPES.has(w.widget_type)).map((w) => w.id)),
-    [widgets]
-  )
-
   // No auto-compaction (widgets stay exactly where dropped, so items in
   // different columns can be aligned freely) and preventCollision blocks
   // dropping onto another widget (it snaps back), so widgets never overlap.
@@ -277,21 +259,20 @@ export function DashboardGrid({
   // whole coarse rows (SCALE-aligned) while dragging/resizing. Otherwise the
   // dropped fine position gets rounded on commit and the widget visibly snaps
   // back, then ping-pongs with RGL's onLayoutChange echo (the "jitter").
-  // Auto-height widgets keep their measured fine height untouched.
+  // content-height widgets keep their measured fine height untouched.
   const updateLiveLayout = useCallback(
     (nextLayout: Layout) => {
       const snapped = nextLayout.map((item) => {
+        const strategy = getStrategy(item.i)
         const base = {
           ...item,
-          y: Math.round(item.y / SCALE) * SCALE,
-          h: autoIdSet.has(item.i) ? item.h : Math.max(SCALE, Math.round(item.h / SCALE) * SCALE)
+          y: Math.round(item.y / SCALE) * SCALE
         }
-        if (squareIdSet.has(item.i)) {
-          // While the user is actively resizing, h follows w in coarse units so
-          // react-resizable's cursor delta tracking stays consistent. On the
-          // idle echo (RGL re-emitting the rendered layout) keep the rendered
-          // pixel-square value so we don't undo the baseLayout override.
-          base.h = interactionStateRef.current === 'resizing' ? base.w * SCALE : visualSquareHFine(base.w)
+        // Snap h to SCALE multiples only for strategies that operate at coarse h.
+        // aspect-square: h is fine pixel-square (RGL constraints handle resize); leave it.
+        // content-height: h locked to measurement; leave it.
+        if (strategy.kind === 'free' || strategy.kind === 'fixed') {
+          base.h = Math.max(SCALE, Math.round(item.h / SCALE) * SCALE)
         }
         return base
       })
@@ -300,7 +281,7 @@ export function DashboardGrid({
       // raw (overlapping) persisted positions over the de-overlapped layout.
       setLiveLayout(deoverlapLayout(snapped))
     },
-    [autoIdSet, squareIdSet, visualSquareHFine]
+    [getStrategy]
   )
 
   // Resync the rendered layout to the widgets-derived one the moment `widgets`
@@ -329,38 +310,44 @@ export function DashboardGrid({
   const commitLayoutChange = useCallback(
     (finalLayout: Layout) => {
       setInteractionState('idle')
-      // Convert the fine grid back to coarse persisted units. Auto-height widgets
-      // persist their height too so a user-grown size sticks (the measured
-      // content height still acts as the floor on the next render).
-      // Snap to coarse rows then resolve any residual penetration. preventCollision
-      // can block the move so no patch is emitted; without this the live layout
-      // would keep the penetrating drag position until the next widgets change.
+
+      // Per-strategy snap. For free/fixed: snap h to coarse multiples. For
+      // aspect-square: apply snapOnRelease's coarse SnapPatch via applyCoarsePatch
+      // (sets w and re-derives fine h via SCALE). Then re-normalize so the live
+      // layout matches what the next baseLayout render will produce.
       const snapped = finalLayout.map((item) => {
-        const base = {
+        const strategy = getStrategy(item.i)
+        const measured = autoUnits[item.i]
+
+        let base = {
           ...item,
-          y: Math.round(item.y / SCALE) * SCALE,
-          h: autoIdSet.has(item.i) ? item.h : Math.max(SCALE, Math.round(item.h / SCALE) * SCALE)
+          y: Math.round(item.y / SCALE) * SCALE
         }
-        if (squareIdSet.has(item.i)) {
-          base.h = visualSquareHFine(base.w)
+        if (strategy.kind === 'free' || strategy.kind === 'fixed') {
+          base.h = Math.max(SCALE, Math.round(item.h / SCALE) * SCALE)
         }
-        return base
+
+        const snap = snapOnRelease(base, strategy, { containerWidth: width })
+        base = applyCoarsePatch(base, snap)
+        return normalizeRenderItem(base, strategy, {
+          containerWidth: width,
+          autoMeasuredFineH: measured
+        })
       })
       const resolved = deoverlapLayout(snapped)
       setLiveLayout(resolved)
+
       const coarseLayout = resolved.map((item) => ({
         ...item,
         y: Math.round(item.y / SCALE),
-        // Squares persist as h_coarse = w_coarse regardless of the visual
-        // fine-height override (which stays a pure render-time concern).
-        h: squareIdSet.has(item.i) ? item.w : Math.round(item.h / SCALE)
+        h: Math.round(item.h / SCALE)
       }))
       const patch = layoutToPatch(coarseLayout, widgets)
       if (patch.length > 0) {
         onLayoutChange(patch)
       }
     },
-    [autoIdSet, squareIdSet, onLayoutChange, widgets, visualSquareHFine]
+    [autoUnits, getStrategy, onLayoutChange, widgets, width]
   )
 
   const sortedWidgets = useMemo(() => {
@@ -371,7 +358,7 @@ export function DashboardGrid({
     return (
       <div className="space-y-4">
         {sortedWidgets.map((widget) => {
-          const isAuto = AUTO_HEIGHT_TYPES.has(widget.widget_type)
+          const isAuto = getStrategy(widget.id).kind === 'content-height'
           return (
             <div className="relative" key={widget.id}>
               {isEditing && (
@@ -419,7 +406,7 @@ export function DashboardGrid({
           width={width}
         >
           {widgets.map((widget) => {
-            const isAuto = AUTO_HEIGHT_TYPES.has(widget.widget_type)
+            const isAuto = getStrategy(widget.id).kind === 'content-height'
             return (
               <div className="relative h-full" key={widget.id}>
                 {isEditing && (

From 355ee38c585e22573b289e86cd57e17f561304b6 Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 02:10:10 +0800
Subject: [PATCH 17/18] chore(web): satisfy useDefaultSwitchClause lint rule
 for sizing strategies

---
 .../src/components/dashboard/sizing-strategies/index.ts   | 8 +++-----
 .../components/dashboard/sizing-strategies/normalize.ts   | 3 +--
 2 files changed, 4 insertions(+), 7 deletions(-)

diff --git a/apps/web/src/components/dashboard/sizing-strategies/index.ts b/apps/web/src/components/dashboard/sizing-strategies/index.ts
index 7d379b17..12073d34 100644
--- a/apps/web/src/components/dashboard/sizing-strategies/index.ts
+++ b/apps/web/src/components/dashboard/sizing-strategies/index.ts
@@ -57,17 +57,13 @@ export function snapOnRelease(item: LayoutItem, strategy: SizingStrategy, _ctx:
       const tier = nearestTier(item.w, strategy.tiers)
       return { w: tier, h: tier }
     }
-    case 'free':
-    case 'fixed':
-    case 'content-height':
+    default:
       return {}
   }
 }
 
 export function applyStrategy(strategy: SizingStrategy, measuredFineH?: number): StrategyDescriptor {
   switch (strategy.kind) {
-    case 'free':
-      return { constraints: [], resizeHandles: undefined, isResizable: true }
     case 'fixed':
       return { constraints: [], resizeHandles: [], isResizable: false }
     case 'aspect-square':
@@ -78,5 +74,7 @@ export function applyStrategy(strategy: SizingStrategy, measuredFineH?: number):
         resizeHandles: ['e'],
         isResizable: true
       }
+    default:
+      return { constraints: [], resizeHandles: undefined, isResizable: true }
   }
 }
diff --git a/apps/web/src/components/dashboard/sizing-strategies/normalize.ts b/apps/web/src/components/dashboard/sizing-strategies/normalize.ts
index 17cb4103..e7c06514 100644
--- a/apps/web/src/components/dashboard/sizing-strategies/normalize.ts
+++ b/apps/web/src/components/dashboard/sizing-strategies/normalize.ts
@@ -37,8 +37,7 @@ export function normalizeRenderItem(item: LayoutItem, strategy: SizingStrategy,
       }
       return item
     }
-    case 'fixed':
-    case 'free':
+    default:
       return item
   }
 }

From f812473c73c7a4e719d1dfb8cd77249a2f605e5c Mon Sep 17 00:00:00 2001
From: ZingerLittleBee <6970999@gmail.com>
Date: Thu, 28 May 2026 02:13:10 +0800
Subject: [PATCH 18/18] docs: add widget sizing contributor + manual
 verification checklists

---
 docs/dashboard-widget-checklist.md      | 30 +++++++++++++++++++
 tests/manual/dashboard-widget-sizing.md | 40 +++++++++++++++++++++++++
 2 files changed, 70 insertions(+)
 create mode 100644 docs/dashboard-widget-checklist.md
 create mode 100644 tests/manual/dashboard-widget-sizing.md

diff --git a/docs/dashboard-widget-checklist.md b/docs/dashboard-widget-checklist.md
new file mode 100644
index 00000000..f7229693
--- /dev/null
+++ b/docs/dashboard-widget-checklist.md
@@ -0,0 +1,30 @@
+# Adding a New Dashboard Widget
+
+This checklist captures the steps to add a new widget type to the dashboard.
+
+## Required
+1. **`apps/web/src/lib/widget-types.ts`** — add a `WidgetTypeDefinition` entry. The `sizing` field is required (TypeScript will fail to compile if you omit it).
+2. **`apps/web/src/components/dashboard/widget-renderer.tsx`** — add a `switch` case for the new `widget_type`.
+3. **`apps/web/src/components/dashboard/widget-picker.tsx`** — register the picker entry (icon + i18n label key).
+4. **`apps/web/src/components/dashboard/widget-config-dialog.tsx`** — add a config form if the widget needs configuration.
+5. **`apps/web/src/locales/{en,zh}/dashboard.json`** — i18n strings for the picker entry and any in-widget text.
+
+## Optional
+- Widget component: `apps/web/src/components/dashboard/widgets/<name>.tsx`
+- Vitest coverage: `apps/web/src/components/dashboard/widgets/<name>.test.tsx`
+
+## Picking a `sizing` strategy
+
+| When the widget is …                                  | Use                                              |
+| ----------------------------------------------------- | ------------------------------------------------ |
+| A chart, table, or generic free-sized panel           | `{ kind: 'free' }`                               |
+| A single fixed-size readout (one viable footprint)    | `{ kind: 'fixed' }` (set minW=maxW, minH=maxH)   |
+| A radial / gauge / aspect-locked visual               | `{ kind: 'aspect-square', tiers: [...] }`        |
+| A list/table that should hug its measured content     | `{ kind: 'content-height' }`                     |
+
+For `aspect-square`, `tiers` is the list of legal coarse-grid sizes (w × w). For gauge today: `[2, 3, 4, 5, 6]` — every integer between minW (2) and maxW (6).
+
+## Related
+
+- Architecture: `docs/superpowers/specs/2026-05-28-dashboard-widget-sizing-strategy-design.md`
+- Strategy dispatcher: `apps/web/src/components/dashboard/sizing-strategies/`
diff --git a/tests/manual/dashboard-widget-sizing.md b/tests/manual/dashboard-widget-sizing.md
new file mode 100644
index 00000000..800cb816
--- /dev/null
+++ b/tests/manual/dashboard-widget-sizing.md
@@ -0,0 +1,40 @@
+# Dashboard Widget Sizing — Manual Verification
+
+Run this checklist after touching `apps/web/src/components/dashboard/dashboard-grid.tsx`,
+`apps/web/src/components/dashboard/dashboard-layout.ts`, or anything in
+`apps/web/src/components/dashboard/sizing-strategies/`.
+
+## Setup
+
+Run `make dev-demo` (admin/admin123). Open the printed URL.
+
+## Aspect-square (gauge)
+
+- [ ] On page load (no interaction), gauge cells are visually pixel-square (1:1).
+- [ ] In edit mode, the gauge's SE handle is visible. No other handles.
+- [ ] Dragging the SE handle keeps the cell visually pixel-square throughout. Cell follows whichever cursor axis (x or y) moved more.
+- [ ] Releasing snaps the cell to the nearest tier in `[2, 3, 4, 5, 6]` (coarse grid units).
+- [ ] After resizing and reloading the page, the gauge is at the same tier — persistence works.
+- [ ] Window resize / sidebar toggle: gauge scales visually but `grid_w` doesn't change.
+- [ ] Two adjacent gauges: dragging into the neighbor blocks growth (existing collision behavior).
+
+## Content-height (top-n)
+
+- [ ] In edit mode, only the east (`e`) handle is visible on Top-N.
+- [ ] Width is resizable; height tracks content measurement.
+
+## Fixed (stat-number)
+
+- [ ] No resize handles on Stat Number widgets in edit mode.
+
+## Free (line-chart, multi-line, traffic-bar, disk-io, alert-list, server-cards, metric-card, …)
+
+- [ ] All 8 handles visible in edit mode.
+- [ ] Resize works smoothly.
+- [ ] Released height is a clean coarse multiple — no fractional pixel offsets.
+
+## Regression checks
+
+- [ ] Browser console has no errors (especially no "Maximum update depth exceeded").
+- [ ] Layout doesn't jitter or flicker during drag/resize.
+- [ ] Layout doesn't shift visibly on release of a resize that didn't change size.