@adia-ai/web-modules 0.8.36 → 0.8.38

package/chat/README.md

@@ -12,7 +12,7 @@ streaming vs. external-drive).
 
 `wireAgentEvents(chatShell, registry, { events, statusEl? })` folds ONE
 `AsyncIterable<AgentEvent>` (`@adia-ai/agent`'s stream contract — see
-[`packages/agent/README.md`](../../agent/README.md#events)) into the thread.
+[`packages/llm/agent/README.md`](../../llm/agent/README.md#events)) into the thread.
 It never touches session state — `reduce(session, event)` is the caller's
 job, the same event object just also flows through this function to paint.
 
@@ -34,7 +34,7 @@ job, the same event object just also flows through this function to paint.
 | `done` | `reasoning.finish()` (or `.fail('Blocked by guardrail')` when `stopReason === 'guardrail_denied'`) + `stopStreaming()`. |
 
 **Why `<agent-reasoning-ui>`, not a new primitive:** the primitive audit
-(adia-author §0) found `agent-reasoning-ui` already built for exactly this
+(primitive-authoring §0) found `agent-reasoning-ui` already built for exactly this
 shape — "Agent inner monologue + pipeline viewer with steps, thoughts,
 plans, and iterations," composing `<timeline-ui>` for step rows with a
 collapsible per-step `outcomes` list (the "collapsible tool-result body"

package/chat/chat-composer/chat-composer.js

@@ -32,8 +32,8 @@
  * backwards compat.
  */
 
-import { defineIfFree } from '../../../web-components/core/register.js';
-import { UIElement } from '../../../web-components/core/element.js';
+import { defineIfFree } from '@adia-ai/web-components/core/register';
+import { UIElement } from '@adia-ai/web-components/core/element';
 
 class ChatComposer extends UIElement {
   static properties = {

package/chat/chat-empty/chat-empty.js

@@ -21,8 +21,8 @@
  * consumer surfaces (patient-visit), so it gets the class.
  */
 
-import { defineIfFree } from '../../../web-components/core/register.js';
-import { UIElement } from '../../../web-components/core/element.js';
+import { defineIfFree } from '@adia-ai/web-components/core/register';
+import { UIElement } from '@adia-ai/web-components/core/element';
 
 class ChatEmpty extends UIElement {
   static properties = {};

package/chat/chat-shell/chat-shell.js

@@ -1,13 +1,13 @@
-import { defineIfFree } from '../../../web-components/core/register.js';
-import { UIElement } from '../../../web-components/core/element.js';
-import { renderMarkdown } from '../../../web-components/core/markdown.js';
-// LAZY llm import (gh#541): packages/llm/index.js is a BUILD ARTIFACT
+import { defineIfFree } from '@adia-ai/web-components/core/register';
+import { UIElement } from '@adia-ai/web-components/core/element';
+import { renderMarkdown } from '@adia-ai/web-components/core/markdown';
+// LAZY llm import (gh#541): packages/llm/core/index.js is a BUILD ARTIFACT
 // (gitignored; TS source only in a fresh checkout). A static import here
 // rides the everything-barrel, so a missing artifact 500'd EVERY /site
 // route with a full-viewport vite-error-overlay — the freeze-shaped dev
 // failure. Deferred to first send: a missing build degrades chat-shell's
 // LLM wiring with an in-thread error instead of killing the site.
-import '../../../web-components/components/code/code.js';
+import '@adia-ai/web-components/components/code';
 
 function escapeHTML(s) {
   return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
@@ -309,7 +309,7 @@ class ChatShell extends UIElement {
         } catch { /* try next */ }
       }
       if (!streamChat) {
-        this.appendMessage({ role: 'error', content: '@adia-ai/llm is not available — in a fresh checkout run the packages/llm build (see gh#527/gh#541).' });
+        this.appendMessage({ role: 'error', content: '@adia-ai/llm is not available — in a fresh checkout run the packages/llm/core build (see gh#527/gh#541).' });
         this.#emit('error', { error: new Error('llm build artifact missing') });
         return;
       }

package/chat/chat-sidebar/chat-sidebar.js

@@ -37,8 +37,8 @@
  * code should prefer <chat-sidebar>.
  */
 
-import { defineIfFree } from '../../../web-components/core/register.js';
-import { UIElement } from '../../../web-components/core/element.js';
+import { defineIfFree } from '@adia-ai/web-components/core/register';
+import { UIElement } from '@adia-ai/web-components/core/element';
 
 const SNAP_THRESHOLD = 96;
 const SNAP_MIN_USABLE = 160;

package/chat/chat-surfaces/chat-surfaces.js

@@ -29,7 +29,7 @@
  * (unlike `@genui/*`), so `wireAgentEvents` imports `<agent-reasoning-ui>`
  * directly (gh#667) — the "agent inner monologue + pipeline viewer with
  * steps, thoughts, plans, and iterations" primitive already built for
- * exactly this shape (primitive audit, adia-author §0 — no new primitive
+ * exactly this shape (primitive audit, primitive-authoring §0 — no new primitive
  * was minted). One reasoning viewer is lazily mounted per assistant turn
  * and renders `thinking` (→ `addThought`), `tool_use`/`tool_input_delta`/
  * `tool_result` (→ `addStep`/`updateStep`/`completeStep`/`failStep`, with
@@ -39,7 +39,7 @@
  * render-silent (trace is devtools' surface, not the thread's — see the
  * event → rendering table in `packages/web-modules/chat/README.md`).
  */
-import '../../../web-components/components/agent-reasoning/agent-reasoning.js';
+import '@adia-ai/web-components/components/agent-reasoning';
 
 const CLOSED_ANNOTATION_TEXT = 'Closed.';
 const PROTOCOL_VERSION = 'v1.0';
@@ -186,7 +186,7 @@ export const PROGRESS_LABELS = {
  * union already carries `workflow`/`step`/`data`), so no closed-vocabulary
  * `type` amendment is needed to carry this: `workflow: 'plan'` is just a
  * new value inside an already-open string field, the same way
- * `packages/agent/src/workflow.ts`'s own step events use `workflow` for a
+ * `packages/llm/agent/src/workflow.ts`'s own step events use `workflow` for a
  * different named workflow.
  *
  * Code-owned text (CHAT-HARNESS law 3's spirit, applied to `step` the way

package/chat/chat-thread/chat-thread.js

@@ -29,8 +29,8 @@
  * markdown + escape rules); the thread just owns the scroll surface.
  */
 
-import { defineIfFree } from '../../../web-components/core/register.js';
-import { UIElement } from '../../../web-components/core/element.js';
+import { defineIfFree } from '@adia-ai/web-components/core/register';
+import { UIElement } from '@adia-ai/web-components/core/element';
 
 const SCROLL_BOTTOM_TOLERANCE = 40;  // px from bottom that counts as "at bottom"
 

package/dashboard/dashboard-layout/dashboard-layout.a2ui.json

@@ -0,0 +1,254 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/DashboardLayout.json",
+  "title": "DashboardLayout",
+  "description": "Module-tier dashboard-body composite. Crystallizes the recurring\n\"toolbar + KPI grid + chart area + table\" dashboard layout into a\nsingle primitive with four named regions (toolbar / kpis / charts /\ntable) plus an optional aside column. Each region is filled by\nconsumer-supplied <card-ui>s; the composite owns band sizing,\nresponsive breakpoints, and a [density] knob that propagates to\nevery descendant primitive via the parametric --a-density cascade.\n\nSits inside an <admin-page-body>; replaces the hand-rolled\n<col-ui gap=\"4\"> + nested <grid-ui> + <card-ui> chains every\nanalytics consumer reinvents today. Per ADR-0033 (Light-DOM\nsubstrate) — slot= attributes are decorative metadata; CSS rules\nmatch `:scope > [slot=\"X\"]` to position bands in DOM order.\n\nSpec: .claude/docs/specs/implementation-ready/SPEC-018-dashboard-layout.md.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "chart-split": {
+      "description": "Chart-band column split. Empty string = single full-width chart;\n`2` = two equal columns; `2:1` / `3:2` / `3:1` = asymmetric\nratios. Collapses to single column at narrow widths (≤48em).\n",
+      "type": "string",
+      "enum": [
+        "",
+        "2",
+        "2:1",
+        "3:2",
+        "3:1"
+      ],
+      "default": ""
+    },
+    "component": {
+      "const": "DashboardLayout"
+    },
+    "density": {
+      "description": "Spacing scale — propagates --a-density to descendant primitives\nvia CSS custom-property cascade. Empty string inherits whatever\ndensity is in effect on an ancestor (the default — respects an\napp-level density theme). `compact` / `comfortable` / `spacious`\nexplicitly override.\n",
+      "type": "string",
+      "enum": [
+        "",
+        "comfortable",
+        "compact",
+        "spacious"
+      ],
+      "default": ""
+    },
+    "gap": {
+      "description": "Override band-to-band vertical gap. Empty string = the\ndensity-modulated default (--a-space-4 at comfortable). Numeric\n`1`..`6` selects the corresponding --a-space-N step.\n",
+      "type": "string",
+      "default": ""
+    },
+    "kpi-columns": {
+      "description": "Target column count for the KPI band at desktop width. Range 2-6;\nout-of-range values fall back to 4. Container-query collapse\nreduces this at narrower widths (≤48em → 2; ≤32em → 1).\n",
+      "type": "string",
+      "enum": [
+        "2",
+        "3",
+        "4",
+        "5",
+        "6"
+      ],
+      "default": "4"
+    },
+    "loading": {
+      "description": "Marks the composite as data-loading. Sets aria-busy=true on the\nhost and dims slotted children to 60% opacity with pointer-events\nsuppressed. Skeletons inside slotted cards continue to render\nnormally; the dim is on top of them.\n",
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "description": "Child without a [slot] attribute. Lands in the implicit default\nregion and breaks the band layout. Every direct child MUST\ndeclare its slot — toolbar / kpis / charts / table / aside.\n",
+        "right": "<dashboard-layout-ui>\n  <card-ui slot=\"kpis\">...</card-ui>\n</dashboard-layout-ui>\n",
+        "rule": "Every direct child of dashboard-layout-ui declares its slot.\n",
+        "wrong": "<dashboard-layout-ui>\n  <card-ui><!-- no slot -->...</card-ui>\n</dashboard-layout-ui>\n"
+      },
+      {
+        "description": "Nested DashboardLayout. Two density containers fight over the\n--a-density cascade. The inner one re-creates a 2-column layout\ninside a charts band, which is incoherent.\n",
+        "right": "<tabs-ui>\n  <tab-panel-ui><dashboard-layout-ui>...</dashboard-layout-ui></tab-panel-ui>\n  <tab-panel-ui><dashboard-layout-ui>...</dashboard-layout-ui></tab-panel-ui>\n</tabs-ui>\n",
+        "rule": "For nested dashboards, use sibling DashboardLayouts switched by\nTabs — not DashboardLayout inside DashboardLayout.\n",
+        "wrong": "<dashboard-layout-ui>\n  <dashboard-layout-ui slot=\"charts\">...</dashboard-layout-ui>\n</dashboard-layout-ui>\n"
+      },
+      {
+        "description": "kpi-columns out of range. Eight cards in a row is too narrow\nto be legible at typical container widths; the container-query\ncollapse (≤48em → 2 cols, ≤32em → 1 col) won't help when N is\nalready that large at desktop.\n",
+        "right": "<dashboard-layout-ui kpi-columns=\"4\">...</dashboard-layout-ui>\n",
+        "rule": "kpi-columns ∈ {2,3,4,5,6}. Split into 2 rows of 4 by composing\n2 DashboardLayouts vertically if 8 cards are truly necessary.\n",
+        "wrong": "<dashboard-layout-ui kpi-columns=\"8\">...</dashboard-layout-ui>\n"
+      }
+    ],
+    "category": "layout",
+    "composes": [
+      "card-ui",
+      "grid-ui",
+      "row-ui",
+      "stat-ui",
+      "chart-ui",
+      "table-ui"
+    ],
+    "events": {
+      "density-change": {
+        "description": "Fired when [density] changes (programmatic or via setDensity()).\nBubbles; detail.density carries the new value.\n",
+        "detail": {
+          "density": {
+            "description": "The new density value (comfortable / compact / spacious).",
+            "type": "string"
+          }
+        }
+      },
+      "region-empty": {
+        "description": "Fired when a slot transitions from having content to being empty\n(consumer-driven removal of the last child for that slot).\nUseful for parent-level adjust-layout logic.\n",
+        "detail": {
+          "region": {
+            "description": "The slot name that became empty (toolbar / kpis / charts / table / aside).",
+            "type": "string"
+          }
+        }
+      }
+    },
+    "examples": [
+      {
+        "description": "KPI-strip + 2:1 chart split + table band inside an admin page.\n",
+        "a2ui": "[\n  {\n    \"id\": \"dash-1\",\n    \"component\": \"DashboardLayout\",\n    \"density\": \"\",\n    \"kpiColumns\": \"4\",\n    \"chartSplit\": \"2:1\",\n    \"children\": [\"dash-toolbar\", \"dash-kpis\", \"dash-charts\", \"dash-table\"]\n  },\n  {\n    \"id\": \"dash-toolbar\",\n    \"component\": \"Row\",\n    \"slot\": \"toolbar\"\n  },\n  {\n    \"id\": \"dash-kpis\",\n    \"component\": \"Group\",\n    \"slot\": \"kpis\"\n  },\n  {\n    \"id\": \"dash-charts\",\n    \"component\": \"Group\",\n    \"slot\": \"charts\"\n  },\n  {\n    \"id\": \"dash-table\",\n    \"component\": \"Card\",\n    \"slot\": \"table\"\n  }\n]\n",
+        "name": "canonical-analytics-dashboard"
+      },
+      {
+        "description": "Six-KPI dashboard at compact density (power-user view).\n",
+        "a2ui": "[\n  {\n    \"id\": \"dash-2\",\n    \"component\": \"DashboardLayout\",\n    \"density\": \"compact\",\n    \"kpiColumns\": \"6\"\n  }\n]\n",
+        "name": "compact-six-kpi"
+      },
+      {
+        "description": "Dashboard with a sticky aside column carrying a live activity feed.\n",
+        "a2ui": "[\n  {\n    \"id\": \"dash-3\",\n    \"component\": \"DashboardLayout\",\n    \"chartSplit\": \"2\",\n    \"children\": [\"d3-aside\"]\n  },\n  {\n    \"id\": \"d3-aside\",\n    \"component\": \"Card\",\n    \"slot\": \"aside\"\n  }\n]\n",
+        "name": "with-aside-feed"
+      }
+    ],
+    "keywords": [
+      "dashboard",
+      "dashboard-layout",
+      "analytics",
+      "kpi-grid",
+      "chart-area",
+      "dashboard-body",
+      "admin-dashboard",
+      "reporting",
+      "metrics-page",
+      "layout-container"
+    ],
+    "name": "UIDashboardLayout",
+    "related": [
+      "AdminPageBody",
+      "AdminPage",
+      "Card",
+      "Grid",
+      "Stat",
+      "Chart",
+      "Table",
+      "DateRangeSelector"
+    ],
+    "slots": {
+      "aside": {
+        "description": "Optional right-side panel (e.g., live activity feed). When set,\npromotes the host to a 2-column grid with the aside as a sticky\nright column on desktop. Collapses when empty.\n"
+      },
+      "charts": {
+        "description": "Chart band — wrapper containing 1-3 <card-ui> with <chart-ui>.\n[chart-split] drives the grid columns. Collapses when empty.\n"
+      },
+      "kpis": {
+        "description": "KPI band — typically a wrapper element containing N <card-ui>\ninstances each with one <stat-ui>. The composite drives the\ngrid template via [kpi-columns]. Collapses when empty.\n"
+      },
+      "table": {
+        "description": "Table band — typically a single <card-ui slot=\"table\"> containing\n<table-ui> and optional <pagination-ui> in the footer. Full-bleed\nacross the main column. Collapses when empty.\n"
+      },
+      "toolbar": {
+        "description": "Top band — filter chips, segmented date range, global controls.\nTypically a single <row-ui> or <date-range-selector-ui> (SPEC-019).\nCollapses when empty (no row reserved).\n"
+      }
+    },
+    "states": [
+      {
+        "description": "Default; all regions interactive.",
+        "name": "idle"
+      },
+      {
+        "description": "Data fetch in progress; aria-busy=true; content dimmed.",
+        "attribute": "loading",
+        "name": "loading"
+      },
+      {
+        "description": "Compact-density variant; tighter band gaps + density cascade.",
+        "attribute": "density",
+        "name": "compact"
+      },
+      {
+        "description": "Spacious-density variant; looser band gaps + density cascade.",
+        "attribute": "density",
+        "name": "spacious"
+      }
+    ],
+    "status": "experimental",
+    "synonyms": {
+      "charts": [
+        "chart-area",
+        "viz",
+        "graphs"
+      ],
+      "dashboard": [
+        "analytics",
+        "report",
+        "overview",
+        "metrics"
+      ],
+      "kpi": [
+        "metric",
+        "stat",
+        "measure"
+      ],
+      "layout": [
+        "container",
+        "grid",
+        "frame",
+        "shell"
+      ],
+      "tags": [
+        "DashboardLayout",
+        "Dashboard",
+        "AnalyticsDashboard",
+        "MetricsDashboard"
+      ]
+    },
+    "tag": "dashboard-layout-ui",
+    "tokens": {
+      "--dashboard-layout-aside-width": {
+        "description": "Aside column width when [slot=\"aside\"] is present.",
+        "default": "20em"
+      },
+      "--dashboard-layout-chart-gap": {
+        "description": "Inter-card gap inside the chart band.",
+        "default": "var(--a-space-4)"
+      },
+      "--dashboard-layout-gap": {
+        "description": "Band-to-band vertical gap.",
+        "default": "var(--a-space-4)"
+      },
+      "--dashboard-layout-kpi-gap": {
+        "description": "Inter-card gap inside the KPI band.",
+        "default": "var(--a-space-2)"
+      },
+      "--dashboard-layout-padding": {
+        "description": "Outer padding around the composite.",
+        "default": "0"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/dashboard/dashboard-layout/dashboard-layout.css

@@ -0,0 +1,190 @@
+/* ═══════════════════════════════════════════════════════════════
+   <dashboard-layout-ui> — Module-tier dashboard-body composite.
+
+   Owns the four canonical dashboard bands (toolbar / kpis /
+   charts / table) plus an optional aside column. Children declare
+   their band via [slot="X"]; CSS rules position by tag + ancestor
+   + DOM order (per ADR-0033 Light-DOM substrate).
+
+   The composite is a CSS-grid container with named grid-areas;
+   slotted children are placed via `grid-area`. The KPI and chart
+   bands internally drive their own grid via [kpi-columns] and
+   [chart-split] attributes. Density variants override token values
+   only — never `display`, `position`, layout shape.
+
+   Two-block @scope pattern per docs/specs/component-token-contract.md.
+   SPEC: docs/specs/implementation-ready/SPEC-018-dashboard-layout.md.
+   Zero raw color values (repo hard rule); zero raw px ≥ 3 (rem only).
+   ═══════════════════════════════════════════════════════════════ */
+
+/* ── Block 1: TOKEN DECLARATIONS ─────────────────────────────── */
+
+dashboard-layout-ui {
+  --dashboard-layout-gap:           var(--a-space-4);
+  --dashboard-layout-kpi-gap:       var(--a-space-2);
+  --dashboard-layout-chart-gap:     var(--a-space-4);
+  --dashboard-layout-aside-width:   20em;
+  --dashboard-layout-padding:       0;
+
+  /* Loading dim — shared opacity escalation. */
+  --dashboard-layout-loading-opacity:       var(--a-opacity-disabled, 0.6);
+
+  /* Density-modulated gap overrides — applied at the [density="…"]
+     selectors below. Authors can override any of these via the
+     un-suffixed public token (--dashboard-layout-gap etc.). */
+  --dashboard-layout-gap-compact:           var(--a-space-3);
+  --dashboard-layout-kpi-gap-compact:       var(--a-space-2);
+  --dashboard-layout-gap-spacious:          var(--a-space-5);
+  --dashboard-layout-kpi-gap-spacious:      var(--a-space-3);
+}
+
+/* ── Block 2: SCOPED LAYOUT ──────────────────────────────────── */
+
+@scope (dashboard-layout-ui) {
+
+  :scope {
+    display: grid;
+    grid-template-columns: 1fr;
+    grid-auto-rows: auto;
+    grid-template-areas:
+      "toolbar"
+      "kpis"
+      "charts"
+      "table";
+    gap: var(--dashboard-layout-gap);
+    padding: var(--dashboard-layout-padding);
+    /* Provide the container-query substrate so descendant primitives
+       can size against the dashboard container width. Per MEMORY
+       "Size-query provider pattern" — the composite is the
+       acknowledged provider for its descendants. */
+    container-type: inline-size;
+    container-name: dashboard-layout;
+  }
+
+  /* ── Region → grid-area mapping ──
+     Children carry [slot="X"]; CSS places them into the correct band
+     by tag + ancestor + DOM order. */
+  :scope > [slot="toolbar"] { grid-area: toolbar; }
+  :scope > [slot="kpis"]    { grid-area: kpis; }
+  :scope > [slot="charts"]  { grid-area: charts; }
+  :scope > [slot="table"]   { grid-area: table; }
+  :scope > [slot="aside"]   { grid-area: aside; }
+
+  /* ── KPI band — inner grid driven by [kpi-columns] ──
+     Default 4 columns; per-N selectors below override. Each column is
+     `1fr` — equal share of available width. Container queries below
+     (lines @container) collapse to fewer columns at narrow widths;
+     no per-column min-width floor (was minmax(16em, 1fr) — let
+     breakpoints manage responsive behavior, not minmax). */
+  :scope > [slot="kpis"] {
+    display: grid;
+    grid-template-columns: repeat(var(--dashboard-layout-kpi-cols, 4), 1fr);
+    gap: var(--dashboard-layout-kpi-gap);
+  }
+  :scope[kpi-columns="2"] > [slot="kpis"] { --dashboard-layout-kpi-cols: 2; }
+  :scope[kpi-columns="3"] > [slot="kpis"] { --dashboard-layout-kpi-cols: 3; }
+  :scope[kpi-columns="4"] > [slot="kpis"] { --dashboard-layout-kpi-cols: 4; }
+  :scope[kpi-columns="5"] > [slot="kpis"] { --dashboard-layout-kpi-cols: 5; }
+  :scope[kpi-columns="6"] > [slot="kpis"] { --dashboard-layout-kpi-cols: 6; }
+
+  /* ── Chart band — inner grid driven by [chart-split] ──
+     Empty / missing = single full-width chart. */
+  :scope > [slot="charts"] {
+    display: grid;
+    grid-template-columns: 1fr;
+    gap: var(--dashboard-layout-chart-gap);
+  }
+  :scope[chart-split="2"]   > [slot="charts"] { grid-template-columns: 1fr 1fr; }
+  :scope[chart-split="2:1"] > [slot="charts"] { grid-template-columns: 2fr 1fr; }
+  :scope[chart-split="3:2"] > [slot="charts"] { grid-template-columns: 3fr 2fr; }
+  :scope[chart-split="3:1"] > [slot="charts"] { grid-template-columns: 3fr 1fr; }
+
+  /* ── Aside column — promotes the outer grid to 2 columns ──
+     When an [slot="aside"] child is present, the host becomes a
+     2-column grid with all bands stacked in the main column and
+     the aside spanning all rows on the right. */
+  :scope:has(> [slot="aside"]) {
+    grid-template-columns: 1fr var(--dashboard-layout-aside-width);
+    grid-template-areas:
+      "toolbar toolbar"
+      "kpis    aside"
+      "charts  aside"
+      "table   aside";
+  }
+  :scope > [slot="aside"] {
+    align-self: start;
+    position: sticky;
+    top: var(--a-space-4);
+  }
+
+  /* ── Density variants — override TOKEN values only ──
+     Per the contract: variants change tokens; modes change layout.
+     Density is a token-override, not a layout-shape change. */
+  :scope[density="comfortable"] {
+    --a-density: 1;
+  }
+  :scope[density="compact"] {
+    --dashboard-layout-gap:     var(--dashboard-layout-gap-compact);
+    --dashboard-layout-kpi-gap: var(--dashboard-layout-kpi-gap-compact);
+    --a-density:                0.85;
+  }
+  :scope[density="spacious"] {
+    --dashboard-layout-gap:     var(--dashboard-layout-gap-spacious);
+    --dashboard-layout-kpi-gap: var(--dashboard-layout-kpi-gap-spacious);
+    --a-density:                1.15;
+  }
+
+  /* ── Loading state — dim slotted regions ──
+     The composite itself stays interactive (e.g., consumer wants to
+     swap density mid-fetch); only the band content dims + becomes
+     pointer-inert. JS sets aria-busy on the host. */
+  :scope[loading] > [slot] {
+    opacity: var(--dashboard-layout-loading-opacity);
+    pointer-events: none;
+  }
+
+  /* ── Container-query collapse ──
+     At narrow widths the KPI grid collapses regardless of
+     [kpi-columns]; the chart split collapses to single column.
+
+     The selectors mirror the [kpi-columns="N"] / [chart-split="X"]
+     scope rules above so they tie on specificity ([0,2,0]) and win
+     by source order (last-declared, same specificity, in @scope).
+     Without [kpi-columns="N"] in the selector, the higher-specificity
+     scope rule would override the container-query token write. */
+  /* Graduated collapse (bug-14): the old single <48em→2 / <32em→1 was too
+     eager — it dropped a 3-col KPI band to 2 while ~552px still fits 3 cards
+     comfortably. Now the dense bands (5/6) thin first, the authored count
+     holds until cards approach a ~9rem floor, then steps down. */
+  @container dashboard-layout (inline-size < 44em) {
+    :scope[kpi-columns="5"] > [slot="kpis"],
+    :scope[kpi-columns="6"] > [slot="kpis"] {
+      --dashboard-layout-kpi-cols: 3;
+    }
+  }
+  @container dashboard-layout (inline-size < 40em) {
+    :scope[chart-split="2"]   > [slot="charts"],
+    :scope[chart-split="2:1"] > [slot="charts"],
+    :scope[chart-split="3:2"] > [slot="charts"],
+    :scope[chart-split="3:1"] > [slot="charts"] {
+      grid-template-columns: 1fr;
+    }
+  }
+  @container dashboard-layout (inline-size < 32em) {
+    :scope[kpi-columns="3"] > [slot="kpis"],
+    :scope[kpi-columns="4"] > [slot="kpis"],
+    :scope[kpi-columns="5"] > [slot="kpis"],
+    :scope[kpi-columns="6"] > [slot="kpis"] {
+      --dashboard-layout-kpi-cols: 2;
+    }
+  }
+  @container dashboard-layout (inline-size < 20em) {
+    :scope[kpi-columns="2"] > [slot="kpis"],
+    :scope[kpi-columns="3"] > [slot="kpis"],
+    :scope[kpi-columns="4"] > [slot="kpis"],
+    :scope[kpi-columns="5"] > [slot="kpis"],
+    :scope[kpi-columns="6"] > [slot="kpis"] {
+      --dashboard-layout-kpi-cols: 1;
+    }
+  }
+}