@nxgt/material 3.21.0 → 3.22.0

package/dist/pdf-reader.js

@@ -1,3 +1,3 @@
-import { t as e } from "./public-DWuBn4t_.js";
+import { t as e } from "./public-DAF5SCWH.js";
 import { configurePdfReader as t } from "@nxgt/material-core/pdf-reader";
 export { e as PdfReader, t as configurePdfReader };

package/dist/{public-DWuBn4t_.js → public-DAF5SCWH.js}

@@ -17,7 +17,7 @@ import { n as xe, t as Se } from "./toggle-group-BMJNcFAC.js";
 import { o as Ce } from "./escape-owner-C4W_sOAU.js";
 import { n as we } from "./use-slice-reducer-BGkeGtML.js";
 import { r as Te } from "./use-csp-nonce-ZKs9k-ov.js";
-import { n as Ee, t as De } from "./empty-state-CJh9f2pc.js";
+import { n as Ee, t as De } from "./empty-state-lj7vjYWG.js";
 import { t as Oe } from "./client-only.utils-3nHNzCki.js";
 import { t as ke } from "./use-scroll-away-PQRFZkT2.js";
 import { ArrowLeft as Ae, BookOpenText as je, ChevronDown as Me, ChevronLeft as Ne, ChevronRight as Pe, ChevronUp as Fe, Download as Ie, Eraser as Le, FileText as Re, FileWarning as ze, FileX2 as Be, Highlighter as Ve, KeyRound as He, LayoutGrid as Ue, List as We, Loader2 as Ge, Maximize as Ke, MessageSquareText as qe, Minimize as Je, MoreVertical as Ye, MousePointer2 as Xe, MoveHorizontal as Ze, PanelLeft as Qe, Pen as $e, PencilLine as et, Printer as tt, RotateCw as nt, Search as rt, StickyNote as it, Type as at, Underline as ot, Undo2 as st, Volume2 as ct, X as lt, XIcon as ut, ZoomIn as dt, ZoomOut as ft } from "lucide-react";

package/dist/{scene-options-CCy3V7XS.js → scene-options-2zNF3ZkQ.js}

@@ -3,11 +3,13 @@ import { BODY_DEFAULTS as e } from "@nxgt/material-core/backgrounds";
 var t = Object.keys({
 	shapes: 1,
 	density: 1,
+	layout: 1,
 	size: 1,
 	rotate: 1,
 	shapeFill: 1,
-	opacitySpread: 1
-}).filter((e) => e !== "shapes");
+	opacitySpread: 1,
+	icons: 1
+}).filter((e) => e !== "shapes" && e !== "icons");
 function n(e) {
 	return t.map((t) => e?.[t]);
 }

package/dist/theme-picker.js

@@ -1,7 +1,7 @@
 import { t as e } from "./utils-BLfntITJ.js";
 import { a as t, i as n, n as r, o as i, r as a, t as o } from "./bubble-input-B7BVd9fX.js";
 import { t as s } from "./use-material-translation-BFQODuQz.js";
-import { n as c, r as l } from "./icon-sprites-FxHyqyhg.js";
+import { a as c, r as l } from "./icon-sprites-CaYXzOL4.js";
 import { t as u } from "./use-theme-DMcyJ52N.js";
 import { a as d, r as f } from "./theme-context-Cofk6vgs.js";
 import { t as p } from "./theme-toggle-mQzIR1hw.js";
@@ -37,7 +37,7 @@ function D() {
 var O = 4;
 function k(e, t, n = "pro") {
 	try {
-		let r = S(e.iconStyle), i = e.icons ?? "school";
+		let r = S([e.iconStyle ?? []].flat().map((e) => typeof e == "object" && "style" in e ? e.style : e)), i = e.icons ?? "school";
 		return C(i), (typeof i == "string" ? b[i] : i).slice(0, O).map((e, i) => {
 			let [a] = C([e], r[i % r.length]), o = a;
 			return w(n === "free" ? T(o) : o, t);
@@ -50,7 +50,7 @@ function k(e, t, n = "pro") {
 //#endregion
 //#region lib/theme-picker/partials/mini-background.tsx
 function A({ background: e }) {
-	let t = e ? e.preset : "none", n = l(), r = c(), i = e && t === "icons" ? k(e, n, r) : [];
+	let t = e ? e.preset : "none", n = c(), r = l(), i = e && t === "icons" ? k(e, n, r) : [];
 	return /* @__PURE__ */ v("span", {
 		"aria-hidden": !0,
 		"data-slot": "theme-tile-background",

package/dist/themes.js

@@ -9,10 +9,15 @@ import { jsx as y } from "react/jsx-runtime";
 import { THEME_BOOT_SCRIPT as b, themeBootScript as x } from "@nxgt/material-core/theme/boot";
 import { ThemeDefinitionError as S, defineTheme as C } from "@nxgt/material-core/theme/define";
 import { THEME_PRESETS as w, THEME_PRESETS as T, ambre as E, ardoise as D, bleumono as O, bluemoon as k, corail as A, foret as j, lavande as M, menthe as N, ocean as P, pink as F, prune as I, sable as L, slate as R, teal as z } from "@nxgt/material-core/theme/presets";
+//#region lib/themes/define-theme.ts
+function B(t) {
+	return C(t, { warn: e() ? void 0 : (e) => console.warn(e) });
+}
+//#endregion
 //#region lib/themes/nxgt-theme-provider.tsx
-var B = () => () => {}, V = () => v(B, () => !1, () => !0);
-function H({ themes: l = T, defaultTheme: m = o, defaultMode: b, children: x }) {
-	let S = v(c.subscribe, c.getSnapshot, c.getServerSnapshot), C = V(), w = _(() => l.map((e) => e.name), [l]);
+var V = () => () => {}, H = () => v(V, () => !1, () => !0);
+function U({ themes: l = T, defaultTheme: m = o, defaultMode: b, children: x }) {
+	let S = v(c.subscribe, c.getSnapshot, c.getServerSnapshot), C = H(), w = _(() => l.map((e) => e.name), [l]);
 	!e() && !w.includes(m) && f(`defaultTheme "${m}" is not in themes (${w.join(", ")}).`, "NxgtThemeProvider");
 	let E = s(S, w, m), D = l.find((e) => e.name === E), O = b ?? D?.colorScheme ?? "system";
 	g(() => c.claim({
@@ -39,4 +44,4 @@ function H({ themes: l = T, defaultTheme: m = o, defaultMode: b, children: x })
 	});
 }
 //#endregion
-export { m as NxgtTheme, H as NxgtThemeProvider, b as THEME_BOOT_SCRIPT, w as THEME_PRESETS, S as ThemeDefinitionError, E as ambre, D as ardoise, O as bleumono, k as bluemoon, A as corail, C as defineTheme, j as foret, M as lavande, N as menthe, P as ocean, F as pink, I as prune, L as sable, R as slate, z as teal, x as themeBootScript, l as useThemeContext };
+export { m as NxgtTheme, U as NxgtThemeProvider, b as THEME_BOOT_SCRIPT, w as THEME_PRESETS, S as ThemeDefinitionError, E as ambre, D as ardoise, O as bleumono, k as bluemoon, A as corail, B as defineTheme, j as foret, M as lavande, N as menthe, P as ocean, F as pink, I as prune, L as sable, R as slate, z as teal, x as themeBootScript, l as useThemeContext };

package/dist/{use-chat-composer-BBFuKNqC.js → use-chat-composer-B0ze1cU9.js}

@@ -23,7 +23,7 @@ import { t as Mt } from "./spinner-B7HCQMFr.js";
 import { a as Nt } from "./button-tones-BwuVvAmd.js";
 import { a as Pt, i as Ft, n as It, r as Lt, t as Rt } from "./button-rdIhY2BT.js";
 import { t as R } from "./icon-button-ifTpXt0A.js";
-import { n as zt, r as Bt } from "./icon-sprites-FxHyqyhg.js";
+import { a as zt, r as Bt } from "./icon-sprites-CaYXzOL4.js";
 import { t as Vt } from "./use-ssr-media-query-C6M5m8sf.js";
 import { n as Ht, t as Ut } from "./util-4heV2LPI.js";
 import { t as Wt } from "./useEvent-2fKq-6w8.js";
@@ -38,7 +38,7 @@ import { t as sn } from "./compose-refs-DZ0iIVF-.js";
 import { n as cn, r as ln, t as un } from "./chip-CEau88ZV.js";
 import { n as dn, t as fn } from "./icon-badge-CiWXvKCs.js";
 import { r as pn } from "./use-csp-nonce-ZKs9k-ov.js";
-import { t as mn } from "./empty-state-CJh9f2pc.js";
+import { t as mn } from "./empty-state-lj7vjYWG.js";
 import { t as hn } from "./skeleton-DSdtr2qc.js";
 import { H as gn, V as _n, X as vn, bt as yn, it as bn, lt as xn, n as Sn, t as Cn, xt as wn, yt as Tn } from "./dist-moutbfbd.js";
 import { t as En } from "./markdown-Dw_uH7j7.js";
@@ -1140,7 +1140,7 @@ function pu({ items: e, variant: t, tone: n, trigger: r, onCloseAutoFocus: i })
 //#endregion
 //#region lib/components/ui/primitives/icon/icon.tsx
 function mu({ name: e, family: t = "classic", type: r = "duotone", className: i, ...a }) {
-	let o = Bt(), s = zt(), c = $a(Nt) && a["aria-label"] === void 0 && a["aria-labelledby"] === void 0;
+	let o = zt(), s = Bt(), c = $a(Nt) && a["aria-label"] === void 0 && a["aria-labelledby"] === void 0;
 	return /* @__PURE__ */ G("svg", {
 		"data-slot": "icon",
 		role: c ? void 0 : "img",

package/docs/components/navigation-and-layout.md

@@ -205,6 +205,28 @@ import { AuthCard, Button, EmailField, LanguageSwitcher, PasswordField } from '@
 | `brand`, `toolbar` | `ReactNode` | — | the row above the card, left and right; it renders only when one is given |
 | `banner` | `ReactNode` | — | above that row (an update notice) |
 | `footer` | `ReactNode` | — | under the card |
+| `backdrop` | `ReactNode \| false` | the theme's background | what is drawn behind the page: a `Background` preset or any node; `false` for none. Without a theme provider nothing is drawn |
+| `keepClear` | `boolean` | `true` | glyphs (shapes or icons) of the backdrop that would meet the brand row, the card or the page's surfaces, text or controls are dropped (never moved); `false` lets them run under the card |
+
+```tsx
+import { Background } from '@nxgt/material/backgrounds';
+
+<AuthCard title="Sign in" backdrop={<Background preset="shapes" />}>
+  {form}
+</AuthCard>
+```
+
+The backdrop sits in an absolute layer (`data-slot="auth-card-backdrop"`)
+behind the content: `aria-hidden`, `inert`, no pointer events, so it is
+decoration only and never takes a click meant for the form. Under a theme
+provider it is the theme's background (Lavande's gradient included), loaded
+on demand like `ActivityLayout`'s. The keep-clear pass is the one
+`ActivityLayout` uses: after layout, and when the page resizes or changes, a
+glyph (a shape or an icon) whose box meets the card, the brand block or a
+surface, a text or a control of the page (8 px margin) is dropped with a short
+fade, a glyph crossing the layer's edge too; none is cut or moved. Where `ResizeObserver` is missing the scene
+is drawn as it is. The server renders the layer and no measurement, so there
+is no hydration mismatch. Under `prefers-reduced-motion` the fade is off.
 
 A non-error notice goes into a `role="status"` region that is always
 rendered (zero height while empty), so a screen reader announces a notice

package/docs/components/primitives.md

@@ -504,6 +504,27 @@ name to its Free twin (`chevrons-left` to `angles-left`). `useIconEdition()` rea
 // → /static/icons/solid.svg#bell
 ```
 
+`IconSpritesProvider` also takes `backdropSprite`, the reduced sprite that only `Background` reads
+(`nxgt-backdrop-sprite` or `nxgtMaterial({ backdropSprite })` builds it; see
+[the backgrounds guide](../guides/backgrounds.md#a-reduced-sprite-for-the-backdrop)). It has two forms, and a nested
+provider without one keeps its parent's. `useBackdropSprite()` returns its `href`, or `undefined` when none is set. A
+path that is not root-relative or does not end in `.svg` throws `IconRefError` (`base`).
+
+```tsx
+// the object form: the sprite's styles count as served
+<IconSpritesProvider
+	base="/static/icons/"
+	backdropSprite={{ href: '/sprites/backdrop.svg', styles: ['light', 'thin'] }}
+>
+	<Background preset="icons" />
+</IconSpritesProvider>;
+
+// the string form: served styles still come from servedStyles or the edition
+<IconSpritesProvider base="/static/icons/" edition="free" backdropSprite="/sprites/backdrop.svg">
+	<Background preset="icons" />
+</IconSpritesProvider>;
+```
+
 **Storybook:** `Primitives/Icon` · **Vue:** `Icon`
 
 ---

package/docs/guides/app-shell.md

@@ -516,14 +516,15 @@ or an `NxgtTheme` zone around it; see [Themes](./theming.md#the-provider-and-zon
 | `backdrop={<Background … />}` | that node, for this screen |
 | `backdrop={false}` | no background and no blobs: a plain page (`data-plain` on the root) |
 
-**Where the shapes go.** The theme's shapes (the motif and illustrated presets)
-are drawn whole or not at all, and only in empty space. A shape that would cross the layer's edge,
-or reach the app bar, the breadcrumb, the header card or an `EntityHeader`, is
-not drawn (a permanent exclusion). A shape that lies over (or within 8px of) the page's text or
-controls (inputs, buttons, links, images, and every line of text) is hidden: it
-fades out in 150ms (none under `prefers-reduced-motion`) and fades back once
-the content moves away, for instance when the page scrolls or a list changes.
-Shapes are hidden, never moved. The check reads the content when it changes or
+**Where the shapes go (the drop rule).** The theme's shapes and icons (the motif,
+icons and illustrated presets) are drawn whole or not at all, and only in empty space. A
+glyph that would cross the layer's edge, or reach the app bar, the breadcrumb, the header
+card or an `EntityHeader`, is not drawn (a permanent exclusion). A glyph that lies over (or
+within 8px of) a surface (the whole box of a card, a stat card, a table, a data grid, a list,
+an alert or a dialog), a text (every line) or a control (inputs, buttons, links, images) is
+dropped: it fades out in 150ms (none under `prefers-reduced-motion`) and fades back once the
+content moves away, for instance when the page scrolls or a list changes. Glyphs are dropped,
+never moved or resized, so no glyph is left half hidden at a card's edge. The check reads the content when it changes or
 resizes and keeps the boxes, so a scroll only shifts them (one `requestAnimationFrame`-throttled
 pass, well under a millisecond on a typical page; text past the first 6000 boxes is not collected, so a shape may be drawn over it). A moon, a planet or an eclipse counts as one shape: it is hidden whole, with its halo. Limits: a sticky element is measured where it is laid out, not where it sticks, and a late font or image, or an inner scroller, triggers a new check a moment later. Nothing shows until the first
 check has run, so no shape flashes over the content. On a phone, where the

package/docs/guides/backgrounds.md

@@ -50,12 +50,12 @@ import '@nxgt/material/backgrounds.css';
 | `animated` | `boolean`: drifts the layers, see Motion | `false` |
 | `grain` | `boolean`: film noise over the preset; needs `grain.css` | `false` |
 | `seed` | `number`: moves a seeded preset's geometry and the grain | `0` |
-| `motif` | a `MotifOptions` object (`shapes`, `density`, `size`, `rotate`, `shapeFill`, `opacitySpread`), see [Motif presets](#motif-presets) | all fields optional |
+| `motif` | a `MotifOptions` object (`shapes`, `density`, `layout`, `size`, `rotate`, `shapeFill`, `opacitySpread`), see [Motif presets](#motif-presets) | all fields optional |
 | `moon` | a `MoonOptions` object for `preset="moon"`, the celestial presets and a `sky`: `position` (`{ x, y }`, fractions of the container), `phase`, `halo`; see [Moon](#moon) | `{ position: { x: 0.8, y: 0.2 }, phase: 0.78, halo: 2.6 }` |
 | `sky` | `'moon'`, `'eclipse'`, `'meteor-shower'`, `'ringed-planet'` or `'northern-lights'`: a second scene drawn over any preset, before the grain; see [Celestial presets and the sky overlay](#celestial-presets-and-the-sky-overlay) | none |
 | `icons` | for `preset="icons"`: a pack name (`school`, `health`, `finance`, `travel`, `nature`, `tech`) or up to 48 icon names and `{ name, family?, type? }` references; see [Icons](#icons) | the `school` pack |
-| `iconStyle` | for `preset="icons"`: one style (`{ family?, type? }` or a sprite name such as `'sharp-light'`) or a list of at most 8, one drawn per icon | duotone thin |
-| `iconMotif` | for `preset="icons"`: `layout` (`scatter`, `grid`, `constellation`, `drift`), `sizeRange`, `rotation`, `duotone` (`opacity` or `tones`), `secondaryOpacity` (0.4 or, with `tones`, 0.85 unless set), `calm`, `quiet` (`start`, `end`, `center`: a band the icons fade out of) | `{ layout: 'scatter', duotone: 'opacity', calm: true }` (`secondaryOpacity` unset: 0.4, or 0.85 with `tones`) |
+| `iconStyle` | for `preset="icons"` (and `shapes` with `motif.icons`): one style (`{ family?, type? }` or a sprite name such as `'sharp-light'`), a list of at most 8, or a weighted list `[{ style, weight? }]`; one drawn per icon. A weighted list drops the styles whose sprite is not served | light 3, thin 3, sharp-regular 2, sharp-light 2, duotone-thin 1 |
+| `iconMotif` | for `preset="icons"` (and `shapes` with `motif.icons`): `layout` (`even`: shapes and a few icons; `scatter`, `grid`, `constellation`, `drift`: icons only), `colors` (`one`, `palette`, `classic`), `sizeRange`, `rotation`, `duotone` (`opacity` or `tones`), `secondaryOpacity` (0.4 or, with `tones`, 0.85 unless set), `calm` (icons-only layouts), `quiet` (`start`, `end`, `center`: a band the icons fade out of) | `{ layout: 'even', colors: 'one', duotone: 'opacity' }` (`secondaryOpacity` unset: 0.4, or 0.85 with `tones`) |
 | `fill` | `viewport` (the viewport's size) or `container` (its parent's size: the parent needs a definite height) | `viewport` |
 
 
@@ -181,7 +181,7 @@ of path data; `low-poly` is about 20 KB (210 nodes); `circuit` about 9 KB (90 no
 
 <img src="../previews/backgrounds-motifs.webp" width="480" alt="The shapes preset behind a card">
 
-**Behind an `ActivityLayout`** a preset's discrete shapes are hidden wherever they would lie over the page's text or controls, and fade back when the content moves away (see [Where the shapes go](./app-shell.md#the-themes-background)). A `Background` used on its own, on a page you lay out, draws all its shapes.
+**Behind an `ActivityLayout`** a preset's discrete shapes and icons are dropped wherever their box would meet a surface (a card, a table, a list), a text or a control, and fade back when the content moves away (see [The drop rule](#the-drop-rule)). A `Background` used on its own, on a page you lay out, draws all its glyphs.
 
 `shapes`, `confetti-grid`, `constellation`, `halftone`, `truchet`, `floating` and `scatter-icons` draw seeded, deterministic geometry from
 the tone's three colours: the same `seed` gives the same composition on the server and in the
@@ -203,19 +203,26 @@ browser, and a new `seed` redraws it.
 
 | Field | Values | Default | Read by |
 | --- | --- | --- | --- |
-| `shapes` | any of `MOTIF_SHAPES_ALL`: `circle`, `ring`, `square`, `triangle`, `plus`, `line`, `arc`, then `star`, `heart`, `hexagon`, `diamond`, `wave`, `zigzag`, `spiral`, then the Material 3 Expressive ones `m3-cookie-6`, `m3-cookie-9`, `m3-flower`, `m3-clover-4`, `m3-soft-burst`, `m3-sunny`, `m3-gem`, `m3-puffy`; none chosen draws circles | `MOTIF_SHAPES`: the first seven | `shapes`, `confetti-grid`, `halftone`, `truchet`, `floating` (`halftone` takes `circle`, else the first of `square`, `ring`, `plus`; `truchet` draws diagonals for `line` without `arc`; `floating` turns `circle`/`triangle` into blobs, `ring`/`arc` into rings, `square` into squircles and ignores `plus`/`line`; `shapes` and `confetti-grid` are the only presets that draw the added shapes, the others ignore them) |
-| `density` | `low`, `default`, `high`: how many items | `default` | all fifteen |
+| `shapes` | any of `MOTIF_SHAPES_ALL`: `circle`, `ring`, `square`, `triangle`, `plus`, `line`, `arc`, then `star`, `heart`, `hexagon`, `diamond`, `wave`, `zigzag`, `spiral`, then the Material 3 Expressive ones `m3-cookie-6`, `m3-cookie-9`, `m3-flower`, `m3-clover-4`, `m3-soft-burst`, `m3-sunny`, `m3-gem`, `m3-puffy`, then the radial ones `rays`, `dotted-ring`, `concentric`; none chosen draws circles | `MOTIF_SHAPES`: the first seven | `shapes`, `confetti-grid`, `halftone`, `truchet`, `floating` (`halftone` takes `circle`, else the first of `square`, `ring`, `plus`; `truchet` draws diagonals for `line` without `arc`; `floating` turns `circle`/`triangle` into blobs, `ring`/`arc` into rings, `square` into squircles and ignores `plus`/`line`; `shapes` and `confetti-grid` are the only presets that draw the added shapes, the others ignore them) |
+| `density` | `low`, `default`, `high` (0.55, 1 and 1.7 times the preset's count), `medium` (about 160 items on the scene, more than `high` for `shapes`) or a number, the item count on the scene (up to 600, scaled with the frame's area); `moon` and the celestial presets draw `medium` and numbers as `default` | `default` | all fifteen |
+| `layout` | `scatter` (thrown darts that keep clear of each other) or `even` (a jittered grid over the whole frame, one item per cell: no empty corner, no cluster) | `scatter` | `shapes` |
 | `size` | `small`, `mixed`, `large` | `mixed` | all fifteen |
 | `rotate` | `boolean`: turns the items | `false` | `shapes`, `confetti-grid`, `scatter-icons` (tilts up to 35 degrees), the illustrated scenes (up to 35 degrees instead of 8) |
 | `shapeFill` | `filled`, `outline`, `mixed` | `mixed` | `shapes`, `confetti-grid`, `halftone`, `floating` |
 | `opacitySpread` | `uniform`, `varied` | `varied` | all but `halftone` |
 
-`MOTIF_SHAPES` (the default) stays the first seven; pass `shapes: MOTIF_SHAPES_ALL`, or a hand-picked list such as `['star', 'm3-flower', 'wave']`, for the rest. In `shapes` and `confetti-grid` the 15 added shapes are drawn once per scene as a repeated pattern, so their tone, fill and (in `confetti-grid`) turn and size are fixed per shape; the first seven behave as before, item by item. The Storybook story `Backgrounds/Motif shapes/ShapeCatalogue` draws every shape filled and outlined.
+`MOTIF_SHAPES` (the default) stays the first seven; pass `shapes: MOTIF_SHAPES_ALL`, or a hand-picked list such as `['star', 'm3-flower', 'wave']`, for the rest. In `shapes` and `confetti-grid` the 15 added shapes before the radial ones are drawn once per scene as a repeated pattern, so their tone, fill and (in `confetti-grid`) turn and size are fixed per shape; the first seven and the three radial ones are drawn item by item. The Storybook story `Backgrounds/Motif shapes/ShapeCatalogue` draws every shape filled and outlined.
 
-<img src="../previews/backgrounds-motif-shapes.webp" width="480" alt="The 22 motif shapes, each filled and outlined">
+<img src="../previews/backgrounds-motif-shapes.webp" width="480" alt="The motif shapes, each filled and outlined">
 
 ```tsx
 <Background preset="shapes" motif={{ shapes: ['star', 'm3-flower', 'wave'] }} />
+
+// The radial shapes, spread evenly over the whole frame at medium density
+<Background
+	preset="shapes"
+	motif={{ shapes: ['rays', 'dotted-ring', 'concentric'], layout: 'even', density: 'medium' }}
+/>
 ```
 
 A field a preset does not read is ignored. `rotate` defaults to `false`: motifs stay upright
@@ -326,7 +333,7 @@ them. The theme picker draws a small tile for a theme with a celestial preset.
 
 ## Icons
 
-`preset="icons"` scatters Font Awesome icons over a faint wash. The library ships **no icon artwork**: each icon is a
+`preset="icons"` draws a calm mix over a faint wash: motif shapes and, in about one cell in five, a Font Awesome icon, all in one soft tint on an even grid over the whole frame. The library ships **no icon artwork**: each icon is a
 `<use>` of a sprite file your app serves (`/assets/icons/sprites/` by default; `IconSpritesProvider base="/static/icons/"`
 moves it, as for `Icon`; `edition="free"` draws the Free sheets, see the [Free edition](icon-motifs.md#the-free-edition)). Font Awesome Pro is licensed to you, not to this package. The [icon motifs guide](icon-motifs.md) puts icons, skies, illustrations and themes together.
 
@@ -338,12 +345,146 @@ import { Background } from '@nxgt/material/backgrounds';
 	preset="icons"
 	tone="mixed"
 	icons="health" // a pack, or ['rocket', 'star', { name: 'bolt', family: 'sharp', type: 'solid' }]
-	iconStyle={['duotone-thin', 'duotone-light']} // one style or up to 8; an icon's own family/type wins
-	iconMotif={{ layout: 'constellation', duotone: 'tones' }}
+	iconStyle={[{ style: 'light', weight: 3 }, { style: 'duotone-thin' }]} // a weighted list; an icon's own family/type wins
+	iconMotif={{ colors: 'one' }}
+	motif={{ icons: { ratio: 0.2 }, density: 'medium' }}
 	animated
 />;
 ```
 
+Since 3.22 the preset is the mix by default; none of this is needed for it:
+
+- **The mix**: `motif.icons` is `{ pack?, style?, ratio }`. Each cell of an even, jittered grid is an icon with the
+  probability `ratio` (`0.2` for `icons`; `0` is shapes only, `1` icons only), else a motif shape: the `shapes`
+  default set, or `motif.shapes`, with the radial ones (`rays`, `dotted-ring`, `concentric`) counted twice so they show.
+  `motif.density` counts shapes and icons together (`'medium'` by default: about 160 on a 1600 by 1000 scene;
+  `low`, `high` or a number work too). `pack` and `style` default to the `icons` and `iconStyle` props. The same
+  mix is available on `preset="shapes"` with `motif={{ icons: { ratio: 0.3 } }}` (default `medium` density, no
+  quiet mask); it needs `backgrounds/icons.css` (in `backgrounds.css`). The layout is always even there: `motif.layout` is not read.
+- **One tint**: `iconMotif.colors` is `'one'` (default: the primary tone at low contrast, soft in dark, never bright;
+  the shapes sit at about 0.8 of it), `'palette'` (primary, secondary and tertiary at the same contrast, best with
+  `tone="mixed"`) or `'classic'` (the three tones at full strength, as before 3.22). It is a class on the scene root
+  (`ic-c-one`, `ic-c-palette`, `ic-c-classic`); the tint sets `color` as well as `--fa-primary-color`, so flat styles
+  follow.
+- **Styles**: the weighted default is light 3, thin 3, sharp-regular 2, sharp-light 2, duotone-thin 1. A weighted
+  list (the default included) is cut to the sprites your app serves: `IconSpritesProvider servedStyles={['light',
+  'thin']}` lists the files, `edition="free"` serves `regular` and `solid`; the weights of what is left keep their
+  proportions, and with nothing left it draws Free `regular` and `solid`. A plain style or list is never cut.
+
+### A reduced sprite for the backdrop
+
+The backdrop never needs the full per-style sheets (hundreds of KB each). Build one small sprite that holds only the
+backdrop's icon names in the styles you choose, from your own Font Awesome install, and point the provider at it:
+
+```sh
+# reads @fortawesome/fontawesome-pro, else @fortawesome/fontawesome-free, from node_modules
+npx nxgt-backdrop-sprite --pack health --out public/sprites/backdrop.svg --base /sprites/
+# nxgt-backdrop-sprite --pack school --pack health --style light --style thin   (more packs, explicit styles)
+```
+
+```tsx
+<IconSpritesProvider
+	base="/assets/icons/sprites/" // still used by Icon and Illustration
+	backdropSprite={{ href: '/sprites/backdrop.svg', styles: ['light', 'thin', 'sharp-regular', 'sharp-light', 'duotone-thin'] }}
+>
+```
+
+The command prints the exact `backdropSprite` value. With it set, the icon glyphs of `Background` reference
+`/sprites/backdrop.svg#<file>--<name>` (`thin--book-open`) instead of the per-style sheets, and the styles it holds
+count as served (no `servedStyles` needed). The string form, `backdropSprite="/sprites/backdrop.svg"`, leaves
+which styles are served to `servedStyles` (or `edition="free"`).
+
+- `Icon`, `Illustration` and the theme tiles still read `base`; only `Background` reads the reduced sprite
+  (`useBackdropSprite()` returns its `href`).
+- The `href` must be root-relative and end in `.svg`, else `IconSpritesProvider` throws `IconRefError` (`base`).
+  `--base` / `base` is the path from your web root, not Vite's `base`.
+- The command warns when `--out` is not under the `--base` path (`/sprites/` when you give no `--base`).
+
+#### The Free edition
+
+With `edition="free"` the styles served are `regular` and `solid` whatever the object lists, and the weighted default
+falls back to those two. Build the sprite with `--style regular --style solid` for a Free app. Do not combine
+`edition="free"` with a sprite built from a Pro install that holds no `regular` and `solid` symbols: the Free edition
+draws exactly those two styles, so the icons are blank. A Free install alone gives `regular` and `solid`.
+
+#### A Pro-only sprite
+
+A sprite built from a Pro install holds Pro glyphs under your licence. Serve it from your app; never commit it to a
+public repository, publish it in a package or a public Storybook. Keep it out of version control
+(`public/sprites/backdrop.svg` in `.gitignore`) and build it in CI or at `vite build`, from the install you license.
+
+- **CLI or plugin, not both**: pick one. A `public/sprites/backdrop.svg` the command wrote is a static file that Vite serves before the plugin's dev route, so it shadows the plugin's sprite (and goes stale); delete it when you move to the plugin.
+- **Free install**: a Pro-only name (`backpack`, `chevrons-left`) built from a Free install is written under its Free twin's id, and the command and the plugin warn: set `edition="free"` on `IconSpritesProvider`. - **Packs and names**: `--pack` (repeat it) for the icon packs your backdrops draw, and `--icon` for the names of your
+  own `icons` list. **There is no default pack**: with neither, the command fails and shows the fix. Put every pack or
+  name your backdrops draw: a name missing from the sprite shows nothing.
+- **Styles**: `--style` (repeat it). Unset, the default mix cut to what your install has: `light`, `thin`,
+  `sharp-regular`, `sharp-light` and `duotone-thin` come from Font Awesome Pro, and Free alone holds `regular` and
+  `solid`, which the sprite then holds. A style the install lacks, named with `--style`, is an error. A style that does
+  not hold a name takes the glyph of the next style that does, so no symbol is blank.
+- **Where it reads**: each style's `sprites/<file>.svg` in the package (or `svgs/<file>/<name>.svg`), one `<symbol>`
+  per name and style. `--from <folder>` names a Font Awesome package folder when it is not in `node_modules`.
+- **Size**: about 10–14 KB gzipped per pack with the five default Pro styles; a Free pack in `regular` and `solid` is
+  about 3 KB gzipped.
+- **Licence**: the sprite holds glyphs of your own install, under its licence. Serve it from your app, and never
+  commit a Pro sprite to a public repository or a published Storybook.
+
+Or, instead of the command, the Vite plugin runs the same build with the app, and the dev server serves it:
+
+```ts
+// vite.config.ts
+nxgtMaterial({ backdropSprite: { packs: ['health'], styles: ['light', 'thin'], base: '/sprites/', outFile: 'backdrop.svg' } })
+```
+
+See [the Vite plugin guide](vite-plugin.md#the-reduced-backdrop-sprite).
+
+#### The sprites each style needs
+
+Without a reduced sprite, the backdrop draws from per-style sheets at the `IconSpritesProvider` `base`:
+
+| Style (`iconStyle`) | Sprite file | Share in the default mix | Font Awesome |
+| --- | --- | --- | --- |
+| `light` | `light.svg` | 3 | Pro |
+| `thin` | `thin.svg` | 3 | Pro |
+| `sharp-regular` | `sharp-regular.svg` | 2 | Pro (Sharp) |
+| `sharp-light` | `sharp-light.svg` | 2 | Pro (Sharp) |
+| `duotone-thin` | `duotone-thin.svg` | 1 | Pro (Duotone) |
+| `regular`, `solid` | `regular.svg`, `solid.svg` | the fallback when none of the above is served, and the only two served with `edition="free"` | Free |
+
+A plain `iconStyle` (one style, or a list without weights) is drawn as written and needs its own sheets; only a
+weighted list, the default included, is cut to what is served. A reduced sprite replaces all these files for the
+backdrop (`Icon` still reads them).
+
+### Density
+
+`motif.density` counts shapes and icons together.
+
+| Value | Meaning |
+| --- | --- |
+| `'low'`, `'default'`, `'high'` | 0.55, 1 and 1.7 times the preset's own count (as before 3.22) |
+| `'medium'` | the calm mix: about 160 glyphs on a 1600 by 1000 scene; the default of the mix |
+| a number | the count on that scene, up to 600, scaled with the frame's area |
+
+A small frame draws fewer glyphs, a large one more, so the spread stays the same. The drop rule then thins what meets
+content.
+
+### The look before 3.22
+
+The previous look (icons only, scattered, one duotone style, the three tones at full strength) is three explicit props,
+and nothing else changes:
+
+```tsx
+<Background
+	preset="icons"
+	iconStyle="duotone-thin"
+	iconMotif={{ layout: 'scatter', colors: 'classic' }}
+/>
+```
+
+Any layout but `even` draws icons only, `calm` and `quiet` apply to them as before, and `density` and `motif.icons` are
+not read there. In a theme, the same three keys do it: `background: { preset: 'icons', iconStyle: 'duotone-thin',
+iconMotif: { layout: 'scatter', colors: 'classic' } }`. An app that serves only some Pro sprites sets `servedStyles`
+(or `edition="free"`) on its `IconSpritesProvider`, since the new default draws five styles.
+
 - The icons come from a builder in its own chunk, loaded on demand (`@nxgt/material-core/backgrounds/icons`), so the
   preset registry does not grow. A streaming server render has the icons in the first HTML; with `renderToString` the
   scene layer is empty until the chunk has loaded, on the server and on the client alike (no hydration mismatch).
@@ -352,12 +493,13 @@ import { Background } from '@nxgt/material/backgrounds';
 - Colours: the primary layer takes the tone's colours; the second layer of a duotone icon is the same colour at
   `secondaryOpacity` (no default of its own: 0.4 with `duotone: 'opacity'`, 0.85 with `'tones'`, where the second layer takes the next tone; a value you set, 0.4 included, is used in both). Flat styles (`solid`,
   `regular`) take the tone through `currentColor`. A name missing from the sprite of the style drawn shows
-  nothing, so keep a list of styles to ones that share your names. The default style needs `duotone-thin.svg` at the
-  sprite base (see the sprite 404 entry in [troubleshooting](../troubleshooting.md)).
+  nothing, so keep a list of styles to ones that share your names. The default mix needs `light.svg`, `thin.svg`,
+  `sharp-regular.svg`, `sharp-light.svg` and `duotone-thin.svg` at the sprite base, or `servedStyles` for the ones you
+  have (see the sprite 404 entry in [troubleshooting](../troubleshooting.md)).
 - `animated` drifts each icon a few pixels on `translate` (never under `prefers-reduced-motion`, paused while hidden).
-- In an `ActivityLayout` the keep-inside pass hides an icon that would cross the layer's edge or the header band.
+- In an `ActivityLayout` the keep-inside pass drops an icon or a shape that would cross the layer's edge or the header band (see [the drop rule](#the-drop-rule)).
 - A theme can name the preset with `background: { preset: 'icons', icons, iconStyle, iconMotif, sky }`; the props win. The theme picker draws the first four icons in the theme's tile ([themes](themes.md#icon-motifs-in-a-theme)).
-- CSS: `backgrounds/icons.css` (or `backgrounds.css`). Both pull in `backgrounds/icons-quiet.css`, the mask behind `iconMotif.quiet`, which can also be imported alone. React only: `@nxgt/material-vue` does not draw it.
+- CSS: `backgrounds/icons.css` (or `backgrounds.css`). Both pull in `backgrounds/icons-quiet.css`, the mask behind `iconMotif.quiet`, and `backgrounds/icons-tint.css`, the `colors` tints; each can also be imported alone. React only: `@nxgt/material-vue` does not draw it.
 
 ### Keeping text clear of the icons: `quiet`
 
@@ -392,6 +534,23 @@ text sits on the wash alone.
   tone of the wash, light and dark.
 - A theme sets it too: `background: { preset: 'icons', iconMotif: { quiet: 'end' } }`.
 
+## The drop rule
+
+Behind an `ActivityLayout` or an `AuthCard` (the only two that run the pass; a bare `Background` never does), a glyph (a shape or an icon)
+whose box meets the content is **dropped**, never moved or resized. The content is a surface (the whole box of a card,
+a stat card, a table, a data grid, a list, an alert or a dialog), a text or a control, with an 8 px margin, so no glyph
+is left half hidden at a card's edge. A glyph that crosses the layer's edge or reaches the header band is dropped for
+good.
+
+- The server renders every glyph. The drop happens after the first measure, on the client, in one frame (boxes read
+  before any write), so the markup never differs between server and client.
+- A dropped glyph fades out in 150 ms (none under `prefers-reduced-motion`) and fades back when the content moves
+  away. It runs again on resize and when the content changes.
+- The open areas keep their glyphs; the space behind and between cards is empty. `keepClear={false}` on an `AuthCard`
+  lets the glyphs run under the card.
+- See [The theme's background](./app-shell.md#the-themes-background) for the shell and `AuthCard` in
+  [navigation and layout](../components/navigation-and-layout.md#authcard) for the sign-in page.
+
 ## Dark mode
 
 In dark the drawn colours are lifted to a lightness floor: the dark `--primary` is as dim as the light one, which made the
@@ -432,7 +591,7 @@ The gradient ends on `--nxgt-bg-cp`, not `--nxgt-bg-c2`: to recolour it, set
 ## Defaults from the theme
 
 The `Background` of `@nxgt/material/backgrounds` takes what you leave out
-(`preset`, `tone`, `intensity`, `seed`, `motif`, `moon`, `sky`, `grain`, `animated`) from the
+(`preset`, `tone`, `intensity`, `seed`, `motif`, `moon`, `sky`, `grain`, `animated`, and for `icons` also `icons`, `iconStyle`, `iconMotif` (`layout`, `colors`), `motif.icons` and `motif.density`; `ActivityLayout` and `AuthCard` draw it too) from the
 nearest theme (`NxgtThemeProvider` or an `NxgtTheme` zone, see
 [the provider and zones](./theming.md#the-provider-and-zones)), then from the
 defaults above. A prop you pass always wins; the others still come from the theme.
@@ -447,6 +606,45 @@ import { Background } from '@nxgt/material/backgrounds';
 </NxgtTheme>
 ```
 
+### The calm backdrop in a theme
+
+A theme's `background` takes the same knobs as the props, checked by `defineTheme` (a bad icon key or value throws). A bad `motif` key or value is dropped, not thrown: `defineTheme` from `@nxgt/material/themes` warns for each one in development, the `@nxgt/material-core/theme/define` one only through its `{ warn }` option (4.0: an error; see [troubleshooting](../troubleshooting.md#definetheme-theme-x-backgroundmotif-unknown-key-spin-ignored)).
+
+
+```ts
+import { defineTheme } from '@nxgt/material/themes';
+
+export const ecole = defineTheme({
+	name: 'ecole',
+	colors: { primary: '#0b7a75' },
+	background: {
+		preset: 'icons',
+		icons: 'school',
+		// weighted families: a share each (default 1); a style the app does not serve is dropped
+		iconStyle: [
+			{ style: 'light', weight: 3 },
+			{ style: 'sharp-regular', weight: 2 },
+			{ style: 'duotone-thin', weight: 1 },
+		],
+		iconMotif: { layout: 'even', colors: 'one' }, // 'palette' | 'classic'
+		motif: { density: 'medium', icons: { ratio: 0.2 } }, // 'low' | 'high' | a number
+	},
+});
+```
+
+| Key | Values |
+| --- | --- |
+| `iconMotif.layout` | `even` (the mix), `scatter`, `grid`, `constellation`, `drift` |
+| `iconMotif.colors` | `one`, `palette`, `classic` |
+| `iconStyle` | a style, a list (at most 8), or a weighted list `[{ style, weight? }]`, `weight` from 0 to 1000 |
+| `motif.density` | `low`, `default`, `medium`, `high`, or a number from 1 to 600 |
+| `motif.layout` | `scatter`, `even` (the `shapes` preset) |
+| `motif.icons` | `{ pack?, style?, ratio }`, `ratio` from 0 to 1 (`icons` packs and styles as the props) |
+
+`extends` merges `motif` and `iconMotif` key by key; `iconStyle` and `motif.icons` are replaced whole. `definePlainTheme`
+(no icon check) refuses the other icon keys and ignores `motif.icons`. The theme's `iconStyle` list and the app's
+`servedStyles` or `backdropSprite` work together as for the props.
+
 Outside any theme nothing changes. The preset's stylesheet is still yours to
 import. The `/components` `Background` is the gradient alone and does not read
 the theme.

package/docs/guides/icon-motifs.md

@@ -16,7 +16,7 @@ Free works the same way.
 
 | You have | Serve | Use |
 | --- | --- | --- |
-| the Pro 7.3 pack | one sheet per style you draw, in `public/assets/icons/sprites/`: `duotone-thin.svg` (the default look), `duotone.svg`, `solid.svg`, `sharp-solid.svg`… A non-classic family is `<family>-<style>.svg` | the defaults |
+| the Pro 7.3 pack | one sheet per style you draw, in `public/assets/icons/sprites/`: the icon backgrounds' default mix needs `light.svg`, `thin.svg`, `sharp-regular.svg`, `sharp-light.svg` and `duotone-thin.svg`; `Icon`'s default look `duotone-thin.svg`; then `duotone.svg`, `solid.svg`, `sharp-solid.svg`… A non-classic family is `<family>-<style>.svg` | the defaults |
 | Font Awesome Free | `solid.svg`, `regular.svg` and `brands.svg` from `@fortawesome/fontawesome-free/sprites/`, copied to the same folder | `<IconSpritesProvider base="…" edition="free">` once at the root ([Free edition](#the-free-edition)) |
 
 The Free icons are CC BY 4.0: credit Font Awesome where you show them (the
@@ -54,23 +54,39 @@ import { Background } from '@nxgt/material/backgrounds';
   preset="icons"
   tone="mixed"
   icons="health" // a pack, or up to 48 names and { name, family?, type? }
-  iconStyle={['duotone-thin', 'duotone-light']} // one style, or a list of up to 8
-  iconMotif={{ layout: 'constellation', duotone: 'opacity' }}
+  iconStyle={[{ style: 'light', weight: 3 }, { style: 'duotone-thin' }]} // one style, a list of up to 8, or a weighted list
+  iconMotif={{ colors: 'one' }} // 'one', 'palette' or 'classic'
+  motif={{ icons: { ratio: 0.2 }, density: 'medium' }} // the share of icons among the shapes
 />;
 ```
 
-<img src="../previews/backgrounds-icons.webp" width="480" alt="The school pack of icons scattered over a faint wash, around a card">
+Since 3.22 this draws a **calm mix**: motif shapes and, in about one cell in
+five, an icon, all in one soft primary tint on an even grid over the whole
+frame (`preset="shapes"` with `motif.icons` draws the same). The [backgrounds
+guide](backgrounds.md#icons) lists the options.
+
+<img src="../previews/backgrounds-icons.webp" width="480" alt="The calm mix of shapes and a few school icons in one soft tint, in the open space below a dashboard">
 
 - **`icons`**: a pack name (`school`, `health`, `finance`, `travel`, `nature`,
   `tech`: lists of names, drawn in any style) or your own names and
   `{ name, family?, type? }` references. No `icons` draws the `school` pack.
-- **`iconStyle`**: one style (`'duotone-thin'`, `{ family: 'sharp', type: 'solid' }`)
-  or a list of up to 8. Each icon takes one style from the list by the seeded
-  pick, so a seed always draws the same picture. An icon's own `family` / `type`
-  always wins. Keep a list to styles that share your names.
-- **`iconMotif`**: `layout` (`scatter`, `grid`, `constellation`, `drift`),
-  `sizeRange`, `rotation`, `duotone` (`'opacity'`: the second layer is the same
-  tone at 0.4; `'tones'`: the next tone) and `secondaryOpacity`.
+- **`iconStyle`**: one style (`'duotone-thin'`, `{ family: 'sharp', type: 'solid' }`),
+  a list of up to 8, or a weighted list `[{ style, weight? }]`. Each icon takes
+  one style by the seeded pick, so a seed always draws the same picture. An
+  icon's own `family` / `type` always wins. Keep a list to styles that share
+  your names. The default is a weighted list (light 3, thin 3, sharp-regular 2,
+  sharp-light 2, duotone-thin 1): a weighted list is cut to the sprites your app
+  serves (`IconSpritesProvider`'s `servedStyles`, or the Free edition's
+  `regular` and `solid`), keeps the others' proportions, and draws Free
+  `regular` and `solid` when nothing is left.
+- **`iconMotif`**: `layout` (`even`, the default mix of shapes and icons;
+  `scatter`, `grid`, `constellation`, `drift`: icons only), `colors` (`'one'`,
+  `'palette'`, `'classic'`), `sizeRange`, `rotation`, `duotone` (`'opacity'`:
+  the second layer is the same tone at 0.4; `'tones'`: the next tone) and
+  `secondaryOpacity`.
+- **The look before 3.22** is icons only, scattered, in duotone thin and the
+  three tones at full strength:
+  `<Background preset="icons" iconStyle="duotone-thin" iconMotif={{ layout: 'scatter', colors: 'classic' }} />`.
 - `animated` drifts each icon a little; nothing moves under
   `prefers-reduced-motion`. Icons that cannot be drawn (an unknown pack or style,
   a bad name, more than 48) draw `scatter-icons`, with a console warning outside
@@ -192,7 +208,9 @@ Below it, in every `Icon` (so the app shell's menu, `AccountMenu`,
 every theme tile:
 
 - a style Free lacks is drawn from `solid.svg`: the default duotone, `thin`,
-  `light`, `sharp-*` and every other family. `regular` and `brands` stay;
+  `light`, `sharp-*` and every other family. `regular` and `brands` stay. An
+  icon background's weighted `iconStyle` (the default mix included) draws
+  `regular` and `solid` instead, since no Pro style is served;
 - a Pro-only name is renamed to its Free twin, the same one in every place
   (the table below, plus `chevrons-*` to `angles-*`, `badge-check` to
   `circle-check`, `loader` to `spinner`).