@nxgt/material 3.20.0 → 3.22.0

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # @nxgt/material
 
+## 3.22.0
+
+### Minor Changes
+
+- [#1520](https://github.com/softistx/nxgt-material/pull/1520) [`a8bd7b0`](https://github.com/softistx/nxgt-material/commit/a8bd7b0e40fe89e73dc17dfd2870122248707656) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `AuthCard` takes a `backdrop` ([#1507](https://github.com/softistx/nxgt-material/issues/1507)): the nearest theme's background by default (nothing without a theme provider), a `Background` preset or any node when given, `false` for none. It is drawn in an absolute, `aria-hidden`, inert layer behind the page, and keeps clear of the brand row, the card and the page's surfaces, text and controls with the same pass as `ActivityLayout`'s (`keepClear`, `true` by default; `false` lets the shapes run under the card). The shapes that meet the content are dropped, never moved.
+  
+  **Visual change:** an `AuthCard` under a theme provider now draws the theme's background. Pass `backdrop={false}` to keep the plain page.
+
+- [#1578](https://github.com/softistx/nxgt-material/pull/1578) [`789d95e`](https://github.com/softistx/nxgt-material/commit/789d95e0ef86f03d7c83453355507e885906be29) Thanks [@SteveGT96](https://github.com/SteveGT96)! - The calm backdrop ([#1506](https://github.com/softistx/nxgt-material/issues/1506), [#1507](https://github.com/softistx/nxgt-material/issues/1507)), in one picture. The slices above carry the details; this is what changes for an app and how to get the old look back.
+  
+  **Visual change, by default.**
+  
+  - `Background preset="icons"` (and a theme that names it) draws shapes and about one icon in five, in **one** soft tint, at `medium` density, spread evenly over the frame, with the new radial shapes (`rays`, `dotted-ring`, `concentric`), in a weighted mix of five icon styles (light 3, thin 3, sharp-regular 2, sharp-light 2, duotone-thin 1). A glyph that meets a card, a table, a list, a text or a control is dropped, never moved.
+  - `AuthCard` draws the theme's background by default, with the brand and the card kept clear (`backdrop={false}` for the plain page).
+  - **Upgrade action:** an `IconSpritesProvider` without `servedStyles` → add `servedStyles` listing the sprite files you serve (or the reduced sprite); otherwise icons whose style you do not serve are blank. `edition="free"` is the shortcut for Free `regular` and `solid`: a style that is not served is dropped, and with none left the scene draws those two.
+  
+  **The reduced sprite.** The backdrop no longer needs the full Font Awesome sheets: `npx nxgt-backdrop-sprite --pack school` (or `nxgtMaterial({ backdropSprite: { packs: ['school'] } })`) builds one sprite of a few KB from your own install, and `IconSpritesProvider backdropSprite` reads it. A pack or an icon list is required.
+  
+  **Theme keys.** `defineTheme` accepts and checks the knobs in a theme's `background`, and each one reaches the scene: `iconMotif.layout: 'even'`, `iconMotif.colors` (`'one' | 'palette' | 'classic'`), a weighted `iconStyle` list (`[{ style, weight? }]`), `motif.icons { pack, style, ratio }` and `motif.density` (`'low' | 'medium' | 'high'` or a count from 1 to 600). `motif` is checked for every preset: an unknown key, a `layout` or `density` outside these lists, or a bad `motif.icons` is ignored and never throws (**4.0:** a strict error): core's `defineTheme(definition, { warn })` (new option) tells `warn`, and `@nxgt/material`'s `defineTheme` passes `console.warn` outside production; `definePlainTheme` ignores `motif.icons` like the other icon keys.
+  
+  **The previous look.** Three props, in a theme the same keys: `<Background preset="icons" iconStyle="duotone-thin" iconMotif={{ layout: 'scatter', colors: 'classic' }} />`.
+  
+  **Size.** The core `/backgrounds` entry weighs 25449 B gzipped (budget 25600 B) and the `/backgrounds/icons` builder about 2780 B (budget 3072 B); the theme budgets grew by about 256 B for the whole entry and 128 B for `/theme/define`.
+  
+  Docs: the backgrounds guide (the mix, density, colours, families and weights, the drop rule, the reduced sprite, the sprites each style needs, the previous look, the theme keys), troubleshooting, the theming and themes guides, the core README and docs; the `nxgt-material` plugin's `compose-scenes` and `build-a-theme` skills teach the new defaults.
+  
+  **Vite `base`.** `nxgtMaterial({ backdropSprite })` honours Vite's `base`: the file is still emitted under the plugin `base` (`dist/sprites/backdrop.svg`), while the dev server and the logged `backdropSprite` href carry Vite's `base` (`/app/sprites/backdrop.svg`).
+
+- [#1544](https://github.com/softistx/nxgt-material/pull/1544) [`139a9da`](https://github.com/softistx/nxgt-material/commit/139a9da525e22110ac1de3873da8ea8f07225c59) Thanks [@SteveGT96](https://github.com/SteveGT96)! - The backdrop of `ActivityLayout` and `AuthCard` (the only two that run the pass; a bare `Background` never does) now drops every glyph whose box meets the content (8 px margin), never moving or resizing it. The content now includes the whole box of a card, a stat card, a table, a data grid, a list (`ul`, `ol`), an alert or a dialog, not only the text and controls inside, so no glyph is left half hidden at a card's edge. The server still renders every glyph; the drop happens after the first measure on the client (batched in one frame, boxes read before any write), with a 150 ms fade (none under reduced motion), and again on resize and when the content changes.
+  
+  **Visual change:** the open areas keep their glyphs; the space behind and between cards and lists is empty.
+
+- [#1541](https://github.com/softistx/nxgt-material/pull/1541) [`fc76acb`](https://github.com/softistx/nxgt-material/commit/fc76acb75cd997027d043af483265760096ea8b0) Thanks [@SteveGT96](https://github.com/SteveGT96)! - Backgrounds, the calm mixed backdrop ([#1506](https://github.com/softistx/nxgt-material/issues/1506)): `preset="icons"` draws shapes and a few icons in one soft tint by default. **The default look of `preset="icons"` changes**; no prop is removed and the old look stays reachable by props.
+  
+  - `motif.icons` (new, `{ pack?, style?, ratio }`, type `MotifIcons`) on `preset="shapes"`: each cell of an even, jittered grid is an icon with the probability `ratio`, else a motif shape (the calm default set, the radial ones counted twice so they show; sizes smaller and closer together than the plain preset's). `motif.density` counts shapes and icons together (`medium` unless set). Core draws the shapes; `iconCells()` of `@nxgt/material-core/backgrounds/icons` supplies the icons through the new `SceneOptions.iconCells`. Plain `shapes` scenes are byte-identical to before.
+  - `preset="icons"` is that mix by default: `ratio` 0.2, `medium` density, `iconMotif.layout: 'even'` (new, the default), `colors: 'one'`. Any other layout (`scatter`, `grid`, `constellation`, `drift`) draws icons only, as before.
+  - `iconMotif.colors` (new): `'one'` (default) the primary tone at low contrast, soft in dark, never bright, with the shapes at about 0.8 of it; `'palette'` primary, secondary and tertiary at the same contrast; `'classic'` the three tones at full strength. A class on the scene root (`ic-c-one`, `ic-c-palette`, `ic-c-classic`); the tint sets `color` and `--fa-primary-color`, so flat styles follow.
+  - `iconStyle` takes a weighted list `[{ style, weight? }]` (types `IconStyleMix`, `IconStyleWeight`). The default is light 3, thin 3, sharp-regular 2, sharp-light 2, duotone-thin 1 (it was duotone thin). A weighted list is cut to the sprites the app serves: the new `IconSpritesProvider` prop `servedStyles` lists the files (`edition="free"` serves `regular` and `solid`); the weights of what is left keep their proportions, and with nothing left the scene draws Free `regular` and `solid`. A plain style or list is never cut.
+  - To keep the look before this release: `<Background preset="icons" iconStyle="duotone-thin" iconMotif={{ layout: 'scatter', colors: 'classic' }} />`.
+  - Apps that serve only some Pro sprites (or none) should set `servedStyles` (or `edition="free"`) on their `IconSpritesProvider`: the new default draws five styles.
+  - Core: `buildIconScene` reads `servedStyles` and weighted styles too; new exports `iconCells`, `DEFAULT_STYLE_MIX`, `toningClasses`, `resolveStyleMix`, `IconCells`, `IconCell`, `IconColors`. `useServedStyles()` joins `useSpriteBase()` and `useIconEdition()`.
+
+- [#1519](https://github.com/softistx/nxgt-material/pull/1519) [`3ff19d3`](https://github.com/softistx/nxgt-material/commit/3ff19d3dbbc351b9a3414f323eb9a5274d708d0f) Thanks [@SteveGT96](https://github.com/SteveGT96)! - Backgrounds, the motif engine of the calm backdrop ([#1506](https://github.com/softistx/nxgt-material/issues/1506)): three radial shapes, an even layout and a `medium` density. No default changes: a scene drawn with the same seed and options as before is byte-identical.
+  
+  - New motif shapes `rays` (eight spokes round an empty centre), `dotted-ring` (twelve dots on a circle) and `concentric` (three rings), appended to `MOTIF_SHAPES_ALL` (now 25) and to the `MotifShape` union. They are drawn item by item, so their stroke keeps a readable width at small sizes. The `checker` and `diagonal-checker` marks keep to the first 22 shapes.
+  - `motif.layout` (new, `shapes` only): `'scatter'` (default, as before) or `'even'`, a seeded, jittered grid over the whole frame with one item per cell: no empty corner, no cluster, the same scene for the same seed (SSR). New type `MotifLayout`. The sizes still come from `motif.size`; a size above 62 % of the cell's short side is brought down so a large item does not take its neighbours' place.
+  - `motif.density` also takes `'medium'` (about 160 items on the 1600 x 1000 scene, the count of the calm mix) or a number, the item count on that scene (up to 600, scaled with the frame's area). `low`, `default` and `high` keep their meaning. The presets with three rows (`halftone`, `truchet`, `constellation`, `confetti-grid`, `floating`) read `medium` and counts from 113 as `high` and counts under 66 as `low`; `moon` and the celestial presets draw `medium` and numbers as `default`. New types `MotifDensity` (widened) and `NamedDensity`.
+
+- [#1545](https://github.com/softistx/nxgt-material/pull/1545) [`72f20b0`](https://github.com/softistx/nxgt-material/commit/72f20b044b8c6c18429a7f556f00e7c36e73f2bd) Thanks [@SteveGT96](https://github.com/SteveGT96)! - Backgrounds, a reduced backdrop sprite ([#1506](https://github.com/softistx/nxgt-material/issues/1506)): the backdrop never needs the full Font Awesome sheets. One small SVG sprite holds only the pack's icon names in the styles you choose, built from your own `@fortawesome/*` install.
+  
+  - New command `nxgt-backdrop-sprite` (a bin of `@nxgt/material`, also of `@nxgt/material-core`): `--pack` and `--icon` (one of them is required: there is no default pack, the command fails and shows the fix), `--style` (default: the backdrop's light, thin, sharp-regular, sharp-light and duotone-thin that the install has, else `regular` and `solid`), `--out` (default `public/sprites/backdrop.svg`), `--base` (default `/sprites/`), `--from`. It reads `@fortawesome/fontawesome-pro`, else `-free`, and prints the `IconSpritesProvider` value. One `<symbol id="<file>--<name>">` per name and style; a style that lacks a name takes the glyph of the next one. 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. `--out` not under `--base` warns.
+  - `nxgtMaterial({ backdropSprite: { packs? | icons?, styles?, outFile?, base?, sources? } })` (`packs` or `icons` required; `true` is not accepted) in the Vite plugin: the same build at `vite build` (emitted under `base`) and served by the dev server. Core exports `buildBackdropSprite`, `backdropSpriteHref`, `runBackdropSprite`, `runBackdropSpriteCli` and the types `BackdropSpriteOptions` and `BackdropSpriteResult` from `/vite`.
+  - `IconSpritesProvider backdropSprite` (new): `"/sprites/backdrop.svg"`, or `{ href, styles }` whose styles count as served. `Background preset="icons"` then draws `<use href="/sprites/backdrop.svg#thin--book-open">` instead of the per-style sheets; `Icon` and `Illustration` still read `base`. New hook `useBackdropSprite()`. An href that is not root-relative throws `IconRefError` (`base`).
+  - Core: `IconSceneOptions.backdropSprite` (and `iconCells`), `backdropSymbolId` in `/backgrounds/icons`; `assertSafeScene` accepts `#file--name` ids in a sprite reference.
+  - Docs: the backgrounds guide lists the sprites each style needs, the command and the troubleshooting entry for blank icons.
+
+### Patch Changes
+
+- Updated dependencies [[`789d95e`](https://github.com/softistx/nxgt-material/commit/789d95e0ef86f03d7c83453355507e885906be29), [`fc76acb`](https://github.com/softistx/nxgt-material/commit/fc76acb75cd997027d043af483265760096ea8b0), [`3ff19d3`](https://github.com/softistx/nxgt-material/commit/3ff19d3dbbc351b9a3414f323eb9a5274d708d0f), [`72f20b0`](https://github.com/softistx/nxgt-material/commit/72f20b044b8c6c18429a7f556f00e7c36e73f2bd)]:
+  - @nxgt/material-core@0.34.0
+
+## 3.21.0
+
+### Minor Changes
+
+- [#1602](https://github.com/softistx/nxgt-material/pull/1602) [`800051d`](https://github.com/softistx/nxgt-material/commit/800051ddb782564801354793fe59c3a2bf9589c3) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `DateField` / `DateFormField` / `DateRangeField` keep a value outside `minDate`, `maxDate`, `disablePast` or `disableFuture` (one set from the form or typed) instead of moving it onto the bound's day with its time of day, which turned a moment after midnight into one 24 hours earlier and let a form rule pass; the form refuses it and the calendar still keeps the day unpickable. The `Chip` dismiss ✕ has its own 24x24 box (44x44 on a coarse pointer), so axe `target-size` passes; the glyph and the chip height are unchanged. Fixes [#1583](https://github.com/softistx/nxgt-material/issues/1583). Fixes [#1584](https://github.com/softistx/nxgt-material/issues/1584).
+  
+  Migration: a typed date outside `minDate`/`maxDate`/`disablePast`/`disableFuture` is no longer moved to the nearest allowed day on blur. It is kept, and the form refuses it. If your schema has no min/max rule, add one (see date-and-time.md).
+
 ## 3.20.0
 
 ### Minor Changes

package/README.md

@@ -197,12 +197,12 @@ reads `duotone.svg`, the file that exists (it used to ask for the missing
 | `@nxgt/material/draw` | Vector drawing: a scene of plain data or JSX primitives drawn as accessible, themeable SVG that is safe under a strict CSP and identical on the server and in the browser. `Drawing` (`DrawingProps`, `NodeHandlers`; `scene` or `w`/`h` with children; a `title` (with an optional long `description`, written as a `<desc>`) or `decorative`, enforced by the type), the primitives `Rect`, `Ellipse`, `Circle`, `Line`, `Polygon`, `Path` (takes `node`), `Text`, `Group` and `Image`, and the builders of `@nxgt/material-core/draw` re-exported by name (`scene`, `rect`, `ellipse`, `circle`, `line`, `polygon`, `path`, `text`, `group`, `image`, `linear`, `radial`, `pattern`, `hatch`, `tone`, `toSVG`, `compileScene`, `ROLES`, `DRAW_PALETTE`, and the types `Scene`, `DrawNode`, `Paint`, `Role`, `ToneRef`), plus Material 3 Expressive's shapes (`shape`, `morph`, `SHAPE_NAMES`, `toCubics`) and the layout helpers (`bbox`, `stack`, `grid`, `align`, `distribute`) re-exported by name. Colours are theme roles (`primary-container`, `on-surface`...) mapped to classes in `styles.css`, so import it. Interactive nodes are focusable `button`s with a focus ring; wrapped text is re-measured by the browser once mounted. **Its own entry, client-only** (render `Drawing` from a `'use client'` file; the builders and `toSVG` run anywhere), not in the barrel above ([drawing guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/drawing.md)) |
 | `@nxgt/material/draw/sketch` | The sketchy, hand-drawn style for a drawing: `Sketch` (`seed`, `roughness`, `bowing`, `fill`: `hachure`, `cross-hatch`, `solid` or `none`, `hachureAngle`, `hachureGap`, `strokeWidth`) wraps a `Drawing`, or primitives inside one, and draws shapes as double wobbling strokes with hatched fills; `sketch(sceneOrNode, options)` does it to plain data for `toSVG`. Seeded, so the server and the client draw the same lines; ids, labels, focus rings and events keep working. **Its own entry, client-only** (render `Sketch` from a `'use client'` file), not in the barrel above ([drawing guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/drawing.md#sketch)) |
 | `@nxgt/material/map` | Leaflet maps, markers, a location field — **its own entry, not in the barrel, and browser-only** ([maps guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/maps.md)) |
-| `@nxgt/material/themes` | `NxgtThemeProvider` (the registry, the persisted theme name, `<html data-nxgt-theme>`, `defaultMode`; renders no element; `useTheme({ defaultMode })` takes the first-visit mode too), `NxgtTheme` (a zone in another theme, `mode`, `asChild`), `useThemeContext`, `defineTheme`, `ThemeDefinitionError`, `themeBootScript` and `THEME_BOOT_SCRIPT` (with `ThemeBootOptions`), the 14 presets and `THEME_PRESETS`, `ThemeName` and `NxgtThemes` (augmentable), with the `NxgtThemeProps`, `NxgtThemeProviderProps`, `ThemeContextValue`, `Theme`, `ThemeDefinition` and `ThemeBackground` types ([guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/theming.md#the-provider-and-zones)). `Background` and `ActivityLayout` take their background from the nearest theme |
+| `@nxgt/material/themes` | `NxgtThemeProvider` (the registry, the persisted theme name, `<html data-nxgt-theme>`, `defaultMode`; renders no element; `useTheme({ defaultMode })` takes the first-visit mode too), `NxgtTheme` (a zone in another theme, `mode`, `asChild`), `useThemeContext`, `defineTheme` (a bad background `motif` key or value is dropped and warned about in development, 4.0: an error; core's own `defineTheme` warns only through `{ warn }`), `ThemeDefinitionError`, `themeBootScript` and `THEME_BOOT_SCRIPT` (with `ThemeBootOptions`), the 14 presets and `THEME_PRESETS`, `ThemeName` and `NxgtThemes` (augmentable), with the `NxgtThemeProps`, `NxgtThemeProviderProps`, `ThemeContextValue`, `Theme`, `ThemeDefinition` and `ThemeBackground` types ([guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/theming.md#the-provider-and-zones)). `Background` and `ActivityLayout` take their background from the nearest theme |
 | `@nxgt/material/theme-picker` | `ThemePicker`, the theme and mode chooser (swatches and a mini background per theme; `themes`, `value`, `onValueChange`, `showMode`, `showBackground`, `layout`) and `ThemePickerProps`; its own entry so `/themes` stays small ([guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/theming.md#let-users-choose)) |
 | `@nxgt/material/illustrations` | State illustrations: `Illustration` (`scene`: `empty`, `no-results`, `not-found`, `error`, `offline`, `success`, `welcome`, `forbidden`, `maintenance`, `invitation`, `sign-in`, `empty-inbox`, or an id of the `scenes` table it is given; `size`, `title`, `animated`, `hero`, `satellites`, `iconStyle`, `tone`, `duotone`) draws a hero icon on a Material 3 Expressive plate with satellites, from the Font Awesome sprites your app serves (no icon artwork ships); `IllustrationDefaults` (`icons`: `'suggested'` or a table, `iconStyle`, `sets`) opts a subtree's `EmptyState` and `ErrorState` into them; `ILLUSTRATION_SCENES`, `SUGGESTED_ICONS` and the types re-exported from `@nxgt/material-core/illustrations` (`SceneRow`, `SceneTable`), plus `IconStyleInput` and `IconStyleRef` (the `iconStyle` types: `{ family?, type? }` or one of the 37 sprite file names), `SceneId`, `RegisteredScene` and `IllustrationSceneRegistry`, the scene id type that an imported set's ids widen. `unauthorized` and `maintenance` states draw the `forbidden` and `maintenance` scenes. `EmptyState`, `ErrorState` and the `DataTable` empty row (`emptyIllustration`) also take `illustration` as a scene id or `true`. Colours are theme tones in `styles.css`; its own entry ([illustrations guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/illustrations.md)) |
 | `@nxgt/material/illustrations/health` | The health scenes: `HEALTH_SCENES` (`patient-record`, `consultation`, `appointment`, `lab-sample`, `prescription`, `vaccination`, `hospitalisation`, `emergency`, `no-patients`, `lab-results`), `HEALTH_SCENE_IDS`, `HEALTH_SUGGESTED_ICONS`, `HealthScene`; register it with `<IllustrationDefaults sets={[HEALTH_SCENES]}>` so `<Illustration scene="patient-record" />` and `<EmptyState illustration="no-patients" />` work (or pass `scenes={HEALTH_SCENES}` to one `Illustration`); importing it adds the ids to `SceneId`. An app that does not import it does not carry it |
 | `@nxgt/material/illustrations/education` | The education scenes: `EDUCATION_SCENES` (`classroom`, `homework`, `exam-grades`, `timetable`, `attendance`, `enrolment`, `library`, `graduation`, `no-students`, `report-card`), `EDUCATION_SCENE_IDS`, `EDUCATION_SUGGESTED_ICONS`, `EducationScene`; register it with `<IllustrationDefaults sets={[EDUCATION_SCENES]}>` so `<Illustration scene="classroom" />` and `<EmptyState illustration="no-students" />` work (or pass `scenes={EDUCATION_SCENES}` to one `Illustration`); importing it adds the ids to `SceneId`. An app that does not import it does not carry it |
-| `@nxgt/material/backgrounds` | Background presets: `Background` (a superset of the `/components` one: `preset`, `animated`, `grain`, `seed`, `fill`, `motif`, and for `preset="icons"` `icons`, `iconStyle` and `iconMotif`), `AVAILABLE_BACKGROUND_PRESETS` and `AvailableBackgroundPreset` (the 50 ids `Background` draws), `MoonOptions` (the `moon` prop), `IconMotifOptions` (`iconMotif`, with `quiet`: a band the icons fade out of for text), `IconLayout`, `IconQuiet`, `SkyPreset` and `CelestialPreset` (the `sky` ids), `IconsInput` (`icons`), `IconStyleInput` and `IconStyleRef` (`iconStyle`: `{ family?, type? }` or one of the 37 sprite file names, completed by the editor, any other string is a type error), `sky` (`'moon'` or a celestial preset over any preset, also read from the theme's `background.sky`; the four celestial presets and `sky` share the opt-in `@nxgt/material/backgrounds/celestial.css`, also in `backgrounds.css`), `MOTIF_SHAPES_ALL` (the 22 motif shapes), the types and tables (`BACKGROUND_PRESETS`, `BACKGROUND_TONES`, ...) re-exported from `@nxgt/material-core/backgrounds`; its own entry, with an opt-in stylesheet ([backgrounds guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/backgrounds.md)) |
+| `@nxgt/material/backgrounds` | Background presets: `Background` (a superset of the `/components` one: `preset`, `animated`, `grain`, `seed`, `fill`, `motif`, and for `preset="icons"` `icons`, `iconStyle` and `iconMotif`), `AVAILABLE_BACKGROUND_PRESETS` and `AvailableBackgroundPreset` (the 50 ids `Background` draws), `MoonOptions` (the `moon` prop), `IconMotifOptions` (`iconMotif`, with `quiet`: a band the icons fade out of for text), `IconLayout`, `IconQuiet`, `SkyPreset` and `CelestialPreset` (the `sky` ids), `IconsInput` (`icons`), `IconStyleInput` and `IconStyleRef` (`iconStyle`: `{ family?, type? }` or one of the 37 sprite file names, completed by the editor, any other string is a type error), `sky` (`'moon'` or a celestial preset over any preset, also read from the theme's `background.sky`; the four celestial presets and `sky` share the opt-in `@nxgt/material/backgrounds/celestial.css`, also in `backgrounds.css`), `MOTIF_SHAPES_ALL` (the 25 motif shapes), the `MotifLayout` type, the types and tables (`BACKGROUND_PRESETS`, `BACKGROUND_TONES`, ...) re-exported from `@nxgt/material-core/backgrounds`; its own entry, with an opt-in stylesheet ([backgrounds guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/backgrounds.md)) |
 | `@nxgt/material/editor` | The rich text editor: `DocumentEditor` and `DocumentEditorFormField` (with an `outline`, a block handle, focus mode, find and replace, `onUpload`, `onAssist` and `comments`), `CompactEditor` and `CompactEditorFormField`, `RichChatComposer`, `EditorRoot` and the parts (`EditorToolbar`, `EditorContent`, `EditorFooter`, `EditorAssistantPanel`, ...), `useEditor`, the kits (`documentKit`, `compactKit`, `chatKit`, `formNodesKit`), `withFeatures` / `withoutFeatures` and `defineFeature`, and the converters `toHtml`, `toJson`, `toMarkdown`, `fromMarkdown` and `looksLikeMarkdown` — **its own entry, and not in the barrel above**. **Client-only**: import it from a `'use client'` file; `/editor/viewer` is the server-safe one. The `.nxgt-prose` page styles ship in `styles.css` with the component CSS ([DocumentEditor](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/rich-widgets.md#documenteditor)) |
 | `@nxgt/material/editor/viewer` | `RichTextViewer`: shows a saved document (HTML, JSON or Markdown) read-only, **server-safe**, with no editor instance and no `'use client'` ([RichTextViewer](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/rich-widgets.md#richtextviewer)) |
 | `@nxgt/material/code-editor` | `CodeEditor`, `CodeEditorFormField` and `CodeDiff` on Monaco, their theme presets (`theme`: `'app'`, `'moonlight'`, `'soft'`, `CODE_THEMES`), `defineCodeTheme` for your own, the `CodeMarker` and `CodeMarkerSeverity` types of the `markers` prop, `CodeEditorHandle` (its `ref`), `CodeFile` (its `files`), and `configureMonaco` to bundle Monaco instead of loading it from the CDN. **Client-only**: import it from a `'use client'` file. They are no longer exported from the barrels (removed in 3.0; [guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/code-editor.md)) |
@@ -211,7 +211,7 @@ reads `duotone.svg`, the file that exists (it used to ask for the missing
 | `@nxgt/material/media-hls` | `hlsStreaming()` (options `HlsStreamingOptions`, module type `HlsModule`), the HLS adapter for `MediaPlayer`'s `streaming` prop: `hls.js` (an optional peer) loaded lazily wherever the browser has MSE, native HLS otherwise (or with `preferNative`), its levels as the quality menu; its own entry ([streaming guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/media-streaming.md)) |
 | `@nxgt/material/draw/animate` | Animation for `/draw`: `drawOn(scene)` traces strokes and `appear(scene)` fades nodes in, one after the next (`staggerSteps`; they add class names that `styles.css` animates, so a server renders them and there is no inline style); `useDrawingControls(ref)` replays, pauses, plays and finishes them (Web Animations); `morphScenes(a, b, t)`, `useSceneMorph(from, to, active)` and `MorphDrawing` (`from`, `to`, `active`) spring one scene into another. All stop under reduced motion and show the last frame; its own entry, client-only for the hooks ([drawing guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/drawing.md#animate), [reference](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/draw.md#animation-nxgtmaterial-coredrawanimate)) |
 | `@nxgt/material/draw/png` | `drawingToPng(sceneOrSvg, { scale?, background?, colorsFrom? })` and `downloadDrawingPng(source, fileName)` — a drawing (a scene, or a live `<svg>` such as `svgRef.current` of a `<Drawing ref={svgRef}>`) as a PNG `Blob` in the browser, with the page's theme colours resolved, `data:` images inlined and CORS errors named; its own entry, DOM only when called ([drawing guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/drawing.md#png), [reference](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/draw.md#png-nxgtmaterial-coredrawpng)) |
-| `@nxgt/material/vite` | build-time helpers for consumers: `nxgtMaterial()` (a strict CSP by hash or nonce, self-hosted fonts, a styles check, serves the pdf.js worker on the Vite 5–7 dev server, generates your app themes' stylesheets with `nxgtMaterial({ themes })` and the `nxgt-theme` bin: [Themes guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/themes.md), PDFs on a bundled server with `nxgtMaterial({ pdf: { bundle: true } })`: [Vite plugin guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/vite-plugin.md)), `pdfkitStandardFonts()` ([printing guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/printing.md)), `cspAssetsInlineLimit`, a `build.assetsInlineLimit` that never inlines a font ([CSP guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/csp.md#katex-fonts)) |
+| `@nxgt/material/vite` | build-time helpers for consumers: `nxgtMaterial()` (a strict CSP by hash or nonce, self-hosted fonts, a styles check, serves the pdf.js worker on the Vite 5–7 dev server, generates your app themes' stylesheets with `nxgtMaterial({ themes })` and the `nxgt-theme` bin: [Themes guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/themes.md), a reduced backdrop icon sprite from your Font Awesome install with `nxgtMaterial({ backdropSprite })` and the `nxgt-backdrop-sprite` bin, PDFs on a bundled server with `nxgtMaterial({ pdf: { bundle: true } })`: [Vite plugin guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/vite-plugin.md)), `pdfkitStandardFonts()` ([printing guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/printing.md)), `cspAssetsInlineLimit`, a `build.assetsInlineLimit` that never inlines a font ([CSP guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/csp.md#katex-fonts)) |
 | `@nxgt/material/next` | `withNxgtPrint(nextConfig)`: the `next.config.ts` a Next.js route handler that imports `/print` needs, `output: 'standalone'` included. Node only, no dependency on `next` ([printing guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/printing.md#nextjs-serverexternalpackages-and-output-standalone)) |
 | `@nxgt/material/hooks` | `useTheme`, `useIsClient`, `useIsMobile`, `useLocalizedDate`, `useCspNonce`, `useFocusOnMount`, `useSubmitOnce`, … ([helpers](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/helpers.md#nxgtmaterialhooks)) |
 | `@nxgt/material/dnd` | `@dnd-kit` primitives ([helpers](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/helpers.md#nxgtmaterialdnd)) |
@@ -645,7 +645,7 @@ Not components: what the stylesheet gives any element.
 | --- | --- | --- | --- |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/navigation-layout-appshell.webp" width="120" alt="ActivityLayout"> | [`ActivityLayout`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/navigation-and-layout.md#activitylayout), `ActivityContent`, `AppSidebar`, `AppHeader`, `AppBreadcrumb`, `AppBreadcrumbItem`, `AppBreadcrumbSeparator` | App shell: sidebar built from `items`, a header with a mobile sheet, route breadcrumbs and a titled page; entries are real links, and `linkComponent` swaps the link; it draws the theme's background (Lavande's is the gradient), `backdrop` puts a `/backgrounds` preset behind it for one screen, and `backdrop={false}` draws a plain page. `ActivityContent` takes an `aside` side panel (beside the content from 1280px in CSS only, sticky under the app bar, a named `complementary` landmark, stacked below) and `width="form" \| "reading"` to cap the main column with the panel right beside it. See the [app shell guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/app-shell.md). | `ActivityLayout`, `ActivityContent`, `AppSidebar`, `AppHeader`, `AppBreadcrumb` |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/navigation-layout-accountmenu.webp" width="120" alt="AccountMenu"> | [`AccountMenu`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/navigation-and-layout.md#accountmenu) | The app bar's avatar menu: named after the account, the name and e-mail, the app's links, then an optional Theme choice (`themeChoice`) and a destructive Sign out with a busy state. | `AccountMenu` |
-| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/navigation-layout-authcard.webp" width="120" alt="AuthCard"> | [`AuthCard`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/navigation-and-layout.md#authcard) | The frame of a signed-out page: one `main`, a centred card whose title is the `h1` (focusable on an end state), a status or alert notice, a brand and toolbar row, safe-area padding. | `AuthCard` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/navigation-layout-authcard.webp" width="120" alt="AuthCard"> | [`AuthCard`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/navigation-and-layout.md#authcard) | The frame of a signed-out page: one `main`, a centred card whose title is the `h1` (focusable on an end state), a status or alert notice, a brand and toolbar row, safe-area padding, an optional backdrop (the theme's by default) that keeps clear of the card. | `AuthCard` |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/navigation-layout-sidebar.webp" width="120" alt="Sidebar"> | [`Sidebar`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/navigation-and-layout.md#sidebar), `SidebarHeader`, `SidebarContent`, `SidebarFooter`, `SidebarMenuItem`, `SidebarMenuLabel` | Collapsible navigation sidebar with icons, tooltips and active items. | `Sidebar` (same parts) |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/navigation-layout-topappbar.webp" width="120" alt="TopAppBar"> | [`TopAppBar`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/navigation-and-layout.md#topappbar), `BottomAppBar` | Top bar surface, and a bottom bar of icon actions with an active state. | `TopAppBar`, `BottomAppBar` |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/navigation-layout-breadcrumb.webp" width="120" alt="Breadcrumb"> | [`Breadcrumb`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/navigation-and-layout.md#breadcrumb), `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis` | Breadcrumb primitives. | `Breadcrumb` (same parts) |
@@ -762,6 +762,8 @@ The ones that cost the most time. Every error message, with its fix, is in
 | Components render unstyled, no console error | `@source "../node_modules/@nxgt/material/";` in your stylesheet |
 | Toast or drawer unstyled | import `@nxgt/material/styles.css` (or `dist/material.css`) |
 | `<Icon>` is blank | serve `public/assets/icons/sprites/<style>.svg` |
+| `Background preset="icons"` draws its shapes but no icons, or `nxgt-backdrop-sprite` fails with `needs the icon packs your backdrops draw` | build the reduced sprite with the packs you draw (`npx nxgt-backdrop-sprite --pack school --out public/sprites/backdrop.svg --base /sprites/`) and pass the printed `backdropSprite` to `IconSpritesProvider`; or serve the per-style sheets ([blank backdrop](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/troubleshooting.md#backdrop-icons-are-blank-with-a-reduced-sprite), [missing packs](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/troubleshooting.md#backdropsprite-needs-the-icon-packs-your-backdrops-draw)) |
+| `preset="icons"` looks different after 3.22, or its glyphs vanish near cards | the default is the calm mix (shapes and a few icons, one tint, medium density); for the old look pass `iconStyle="duotone-thin" iconMotif={{ layout: 'scatter', colors: 'classic' }}`; a glyph that meets a card, a list or text is dropped on purpose ([troubleshooting](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/troubleshooting.md#the-icons-backdrop-looks-different-after-322)) |
 | `window is not defined` at server boot | load `@nxgt/material/map` through `import()` + `clientOnly` ([maps](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/maps.md#browser-only)) |
 | `Cannot find package '@nxgt/material-core'` at server boot | add `@nxgt/material-core` wherever `@nxgt/material` is in `ssr.noExternal` or `--external` ([troubleshooting](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/troubleshooting.md#cannot-find-package-nxgtmaterial-core)) |
 | `Cannot find package 'react-router'`, or `ERESOLVE` on `react` or `react-router`, after upgrading to 3.0 | `bun add react@^19.3 react-dom@^19.3 react-router@^8.5` ([troubleshooting](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/troubleshooting.md#cannot-find-package-react-router-after-upgrading-to-30)) |

package/bin/nxgt-backdrop-sprite.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// pnpm and bun link only a project's direct dependencies' bins, so the
+// command ships here too; it is core's.
+let cli;
+try {
+	cli = await import('@nxgt/material-core/vite');
+} catch (error) {
+	if (error?.code !== 'ERR_MODULE_NOT_FOUND') throw error;
+	console.error(
+		`@nxgt/material-core is not built or not installed: ${error.message}`,
+	);
+	process.exit(1);
+}
+
+await cli.runBackdropSpriteCli();

package/dist/background-BtSZsTvY.js

@@ -0,0 +1,286 @@
+import { r as e } from "./rolldown-runtime-BFFgcFxR.js";
+import { t } from "./is-production-GLw59WU8.js";
+import { a as n, i as r, n as i, r as a } from "./icon-sprites-CaYXzOL4.js";
+import { a as o, t as s } from "./theme-context-Cofk6vgs.js";
+import { t as c } from "./compose-refs-DZ0iIVF-.js";
+import { t as l } from "./use-background-activity-KxQgelFF.js";
+import { t as u } from "./scene-svg-DJKa5vsg.js";
+import { n as d, r as f, t as p } from "./scene-options-2zNF3ZkQ.js";
+import { Suspense as m, lazy as h, memo as g, useId as _, useMemo as v, useRef as y } from "react";
+import { Fragment as b, jsx as x, jsxs as S } from "react/jsx-runtime";
+import { IconRefError as C, resolveIconStyles as w, resolveIcons as T } from "@nxgt/material-core/icons";
+import { SCENE_LAYER as E, buildBackgroundScene as D, presetLayers as O, resolveBackgroundPreset as k, svgIdPrefix as ee } from "@nxgt/material-core/backgrounds";
+//#region lib/backgrounds/background/available.ts
+var A = [
+	"gradient",
+	"grain",
+	"mesh",
+	"aurora",
+	"spotlight",
+	"bokeh",
+	"rays",
+	"halo",
+	"plasma",
+	"glass",
+	"ripples",
+	"blobs",
+	"paper",
+	"linen",
+	"concrete",
+	"marble"
+], j = [
+	"isometric",
+	"blueprint",
+	"dots",
+	"stripes",
+	"low-poly",
+	"topography",
+	"waves",
+	"hexagons",
+	"circuit",
+	"graph-paper",
+	"checker",
+	"diagonal-checker",
+	"chevrons"
+], M = [
+	"shapes",
+	"confetti-grid",
+	"constellation",
+	"halftone",
+	"truchet",
+	"floating",
+	"scatter-icons",
+	"school",
+	"night-sky",
+	"bubbles",
+	"leaves",
+	"science",
+	"music",
+	"travel",
+	"sport",
+	"moon",
+	"icons"
+], N = [
+	"eclipse",
+	"meteor-shower",
+	"ringed-planet",
+	"northern-lights"
+], P = (e) => N.includes(e), F = [
+	...A,
+	...j,
+	...M,
+	...N
+], I = h(() => import("./icons-scene-M4HBeN2c.js"));
+function L(e) {
+	return /* @__PURE__ */ x("div", {
+		"data-scene": "",
+		"aria-hidden": "true",
+		children: /* @__PURE__ */ x(m, {
+			fallback: null,
+			children: /* @__PURE__ */ x(I, { ...e })
+		})
+	});
+}
+//#endregion
+//#region lib/backgrounds/background/partials/background-layers.tsx
+var R = h(() => import("./celestial-scene-8Muu6f7O.js")), te = g(function({ preset: e, scene: t, grain: n, sky: r, icons: i, ...a }) {
+	return /* @__PURE__ */ S(b, { children: [
+		O(e).map((n) => n === E ? i ? /* @__PURE__ */ x(L, { ...i }, n) : P(e) ? /* @__PURE__ */ x("div", {
+			"data-scene": "",
+			"data-celestial": "",
+			"aria-hidden": "true",
+			children: /* @__PURE__ */ x(m, {
+				fallback: null,
+				children: /* @__PURE__ */ x(R, {
+					name: e,
+					as: "preset",
+					...a
+				})
+			})
+		}, n) : t && /* @__PURE__ */ x("div", {
+			"data-scene": "",
+			"aria-hidden": "true",
+			children: /* @__PURE__ */ x(u, { node: t })
+		}, n) : /* @__PURE__ */ x("div", {
+			"data-layer": n,
+			"aria-hidden": "true"
+		}, n)),
+		r && /* @__PURE__ */ x("div", {
+			"data-layer": "sky-scene",
+			"data-scene": "",
+			"data-celestial": "",
+			"aria-hidden": "true",
+			children: /* @__PURE__ */ x(m, {
+				fallback: null,
+				children: /* @__PURE__ */ x(R, {
+					name: r,
+					as: "sky",
+					base: e,
+					...a
+				})
+			})
+		}),
+		n && /* @__PURE__ */ x("div", {
+			"data-overlay": "grain",
+			"aria-hidden": "true",
+			children: /* @__PURE__ */ x(u, { node: n })
+		})
+	] });
+});
+//#endregion
+//#region lib/backgrounds/background/partials/icons-check.ts
+function z(e, t) {
+	try {
+		e !== void 0 && T(e);
+		let n = Array.isArray(t) ? t.map((e) => e && typeof e == "object" && "style" in e ? e.style : e) : t && typeof t == "object" && "style" in t ? t.style : t;
+		return Array.isArray(n) && n.some((e) => !e) ? "an empty icon style" : (w(n), null);
+	} catch (e) {
+		if (e instanceof C) return e.message;
+		throw e;
+	}
+}
+//#endregion
+//#region lib/backgrounds/background/partials/icons-keys.ts
+var B = Object.keys({
+	layout: 1,
+	colors: 1,
+	sizeRange: 1,
+	rotation: 1,
+	duotone: 1,
+	secondaryOpacity: 1,
+	calm: 1,
+	quiet: 1
+});
+function V(e) {
+	return JSON.stringify(Object.fromEntries(B.flatMap((t) => e?.[t] === void 0 ? [] : [[t, e[t]]])));
+}
+var H = .2;
+function U(e, t, n) {
+	let { icons: r, iconStyle: i, iconMotif: a, motif: o } = t, s = o?.icons, c = a?.layout, l = e === "shapes" ? !!s : e === "icons" && (c === void 0 || c === "even");
+	return {
+		wants: e === "icons" || e === "shapes" && !!s,
+		iconsKey: JSON.stringify(s?.pack ?? r ?? null),
+		styleKey: JSON.stringify(s?.style ?? i ?? null),
+		motifKey: V(a),
+		mixKey: JSON.stringify(l ? {
+			...o,
+			icons: { ratio: s?.ratio ?? H }
+		} : null),
+		servedKey: JSON.stringify(n ?? null)
+	};
+}
+//#endregion
+//#region lib/backgrounds/background/partials/use-icons-scene.ts
+function W(e, { icons: o, iconStyle: s, iconMotif: c, motif: l, idPrefix: u, seed: d, animated: f }) {
+	let p = n(), m = a(), h = r(), g = i(), { wants: _, iconsKey: y, styleKey: b, motifKey: x, mixKey: S, servedKey: C } = U(e, {
+		icons: o,
+		iconStyle: s,
+		iconMotif: c,
+		motif: l
+	}, h), w = v(() => {
+		if (!_) return null;
+		let n = z(JSON.parse(y) ?? void 0, JSON.parse(b) ?? void 0);
+		return n && !t() && console.warn(`Background: icons cannot be drawn (${n}); drawing "${e === "icons" ? "scatter-icons" : e}" instead.`), n;
+	}, [
+		_,
+		e,
+		y,
+		b
+	]);
+	return {
+		preset: w && e === "icons" ? "scatter-icons" : e,
+		iconsScene: v(() => _ && !w ? {
+			seed: d,
+			idPrefix: u,
+			iconsKey: y,
+			styleKey: b,
+			motifKey: x,
+			mixKey: S,
+			servedKey: C,
+			spriteBase: p,
+			backdropSprite: g,
+			edition: m,
+			animated: f
+		} : void 0, [
+			_,
+			w,
+			d,
+			u,
+			y,
+			b,
+			x,
+			S,
+			C,
+			p,
+			g,
+			m,
+			f
+		])
+	};
+}
+//#endregion
+//#region lib/backgrounds/background/background.tsx
+var G = /* @__PURE__ */ e({ Background: () => J }), K = (e) => console.warn(e);
+function q(e, t, n, r, i, a) {
+	return e === "grain" ? null : D(e, f(t, n, r, i, a));
+}
+function ne(e, t) {
+	return D("grain", {
+		idPrefix: `${e}-grain`,
+		seed: t
+	});
+}
+function J({ children: e, ref: n, preset: r, tone: i, intensity: a, animated: u, grain: f, seed: m, motif: h, moon: g, sky: b, icons: C, iconStyle: w, iconMotif: T, fill: E = "viewport", ...D }) {
+	let O = o()?.background || s, A = r ?? O.preset, j = i ?? O.tone ?? s.tone, M = a ?? O.intensity ?? s.intensity, N = u ?? O.animated ?? !1, P = f ?? O.grain ?? !1, I = m ?? O.seed ?? 0, L = h ?? O.motif, R = g ?? O.moon, z = b ?? O.sky, B = y(null), V = v(() => c(B, n), [n]), H = l(B, N), U = ee(_()), { preset: G, iconsScene: J } = W(k(A, F, t() ? void 0 : K), {
+		icons: C ?? O.icons,
+		iconStyle: w ?? O.iconStyle,
+		iconMotif: T ?? O.iconMotif,
+		motif: L,
+		idPrefix: U,
+		seed: I,
+		animated: N
+	}), Y = P || G === "grain", X = L?.shapes ? [...new Set(L.shapes)].sort().join(",") : void 0, Z = JSON.stringify(d(L)), Q = JSON.stringify(p(R)), $ = J !== void 0, re = v(() => $ ? null : q(G, U, I, X, Z, Q), [
+		$,
+		G,
+		U,
+		I,
+		X,
+		Z,
+		Q
+	]), ie = v(() => Y ? ne(U, I) : null, [
+		Y,
+		U,
+		I
+	]);
+	return /* @__PURE__ */ S("div", {
+		"data-slot": "background",
+		...D,
+		ref: V,
+		"data-background": G === "grain" ? "gradient" : G,
+		"data-preset": G,
+		"data-tone": j,
+		"data-intensity": M,
+		"data-fill": E === "container" ? E : void 0,
+		"data-animated": N ? "" : void 0,
+		"data-grain": Y ? "" : void 0,
+		"data-sky": z,
+		"data-paused": N && H ? "" : void 0,
+		children: [/* @__PURE__ */ x(te, {
+			preset: G,
+			scene: re,
+			grain: ie,
+			sky: z,
+			idPrefix: U,
+			seed: I,
+			shapesKey: X,
+			scalarsKey: Z,
+			moonKey: Q,
+			icons: J
+		}), /* @__PURE__ */ x("div", {
+			"data-slot": "background-content",
+			children: e
+		})]
+	});
+}
+//#endregion
+export { G as n, F as r, J as t };

package/dist/backgrounds/css-react/icons-quiet.css

@@ -4,7 +4,7 @@
 	 * band is `--background-quiet` wide (42%), then the icons fade back in over
 	 * 30%. `start` and `end` follow the reading direction. A mask, not a colour:
 	 * the text underneath keeps the wash's own contrast. */
-	[data-background="icons"] > [data-scene] > :is(.ic-q-start, .ic-q-end) {
+	[data-background] > [data-scene] > :is(.ic-q-start, .ic-q-end) {
 		--nxgt-quiet-to: to right;
 		-webkit-mask-image: linear-gradient(
 			var(--nxgt-quiet-to),
@@ -17,14 +17,14 @@
 			#000 calc(var(--background-quiet, 42%) + 30%)
 		);
 	}
-	[data-background="icons"] > [data-scene] > .ic-q-end,
-	[data-background="icons"] > [data-scene]:dir(rtl) > .ic-q-start {
+	[data-background] > [data-scene] > .ic-q-end,
+	[data-background] > [data-scene]:dir(rtl) > .ic-q-start {
 		--nxgt-quiet-to: to left;
 	}
-	[data-background="icons"] > [data-scene]:dir(rtl) > .ic-q-end {
+	[data-background] > [data-scene]:dir(rtl) > .ic-q-end {
 		--nxgt-quiet-to: to right;
 	}
-	[data-background="icons"] > [data-scene] > .ic-q-center {
+	[data-background] > [data-scene] > .ic-q-center {
 		-webkit-mask-image: linear-gradient(
 			to right,
 			#000 calc(50% - var(--background-quiet, 42%) / 2 - 30%),

package/dist/backgrounds/css-react/icons-tint.css

@@ -0,0 +1,98 @@
+/* The tint of the icons scene (`iconMotif.colors`, React only): a class on the
+ * scene root. `ic-c-one` (default) draws every glyph in the primary tone
+ * mixed toward transparent, a low contrast on any surface and a soft one in
+ * dark, never bright; `ic-c-palette` spreads primary, secondary and tertiary
+ * (`k1..k3`) at the same contrast; the rules out-rank icons.css's `.ic.k1..k3` tones; `ic-c-classic` has no rule here (icons.css
+ * gives the tones at full strength). The icons read `--fa-primary-color`
+ * (duotone and the sprites' paint) and `currentColor` (the flat styles), so the
+ * tint sets both. The motif shapes of the mix sit at 0.8 of the icons' tint. */
+@layer components {
+	[data-background] > [data-scene] > :is(.ic-c-one, .ic-c-palette) {
+		--ic-soft: 46%;
+	}
+	:is(.dark, [data-theme="dark"])
+		[data-background]
+		> [data-scene]
+		> :is(.ic-c-one, .ic-c-palette),
+	[data-background]:is(.dark, [data-theme="dark"])
+		> [data-scene]
+		> :is(.ic-c-one, .ic-c-palette) {
+		--ic-soft: 44%;
+	}
+
+	/* One tint. */
+	[data-background] > [data-scene] > .ic-c-one .ic:is(.k1, .k2, .k3) {
+		--ic-tint: color-mix(
+			in oklab,
+			var(--nxgt-bg-t1) var(--ic-soft),
+			transparent
+		);
+		--fa-primary-color: var(--ic-tint);
+		--fa-secondary-color: var(--ic-tint);
+		color: var(--ic-tint);
+	}
+	[data-background] > [data-scene] > .ic-c-one :is(.k1, .k2, .k3):not(.ic) {
+		color: color-mix(
+			in oklab,
+			var(--nxgt-bg-t1) calc(var(--ic-soft) * 0.8),
+			transparent
+		);
+	}
+	[data-background] > [data-scene] > .ic-c-one :is(.ic-ln, .ic-dt) {
+		stroke: color-mix(in oklab, var(--nxgt-bg-t1) var(--ic-soft), transparent);
+		fill: none;
+	}
+	[data-background] > [data-scene] > .ic-c-one .ic-dt {
+		fill: color-mix(in oklab, var(--nxgt-bg-t1) var(--ic-soft), transparent);
+		stroke: none;
+	}
+
+	/* Three tints, the same contrast. */
+	[data-background] > [data-scene] > .ic-c-palette .ic.k1 {
+		--ic-tint: color-mix(
+			in oklab,
+			var(--nxgt-bg-c1) var(--ic-soft),
+			transparent
+		);
+	}
+	[data-background] > [data-scene] > .ic-c-palette .ic.k2 {
+		--ic-tint: color-mix(
+			in oklab,
+			var(--nxgt-bg-c2) var(--ic-soft),
+			transparent
+		);
+	}
+	[data-background] > [data-scene] > .ic-c-palette .ic.k3 {
+		--ic-tint: color-mix(
+			in oklab,
+			var(--nxgt-bg-c3) var(--ic-soft),
+			transparent
+		);
+	}
+	[data-background] > [data-scene] > .ic-c-palette .ic:is(.k1, .k2, .k3) {
+		--fa-primary-color: var(--ic-tint);
+		--fa-secondary-color: var(--ic-tint);
+		color: var(--ic-tint);
+	}
+	[data-background] > [data-scene] > .ic-c-palette .k1:not(.ic) {
+		color: color-mix(
+			in oklab,
+			var(--nxgt-bg-c1) calc(var(--ic-soft) * 0.8),
+			transparent
+		);
+	}
+	[data-background] > [data-scene] > .ic-c-palette .k2:not(.ic) {
+		color: color-mix(
+			in oklab,
+			var(--nxgt-bg-c2) calc(var(--ic-soft) * 0.8),
+			transparent
+		);
+	}
+	[data-background] > [data-scene] > .ic-c-palette .k3:not(.ic) {
+		color: color-mix(
+			in oklab,
+			var(--nxgt-bg-c3) calc(var(--ic-soft) * 0.8),
+			transparent
+		);
+	}
+}