@nxgt/material-core 0.11.1 → 0.13.0

package/dist/vite/libraries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"libraries.d.ts","sourceRoot":"","sources":["../../src/vite/libraries.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,GAAG,oBAAoB,CAAC;AAE1E,MAAM,MAAM,iBAAiB,GAAG;IAC/B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,wBAAgB,eAAe,CAAC,IAAI,EAAE,mBAAmB,GAAG,iBAAiB,CAQ5E"}

package/dist/vite/nxgt-material.d.ts

@@ -0,0 +1,12 @@
+import type { Plugin } from 'vite';
+import { type NxgtMaterialLibrary } from './libraries';
+import { type NxgtMaterialOptions } from './options';
+/**
+ * The one Vite plugin for `@nxgt/material` and `@nxgt/material-vue`: a strict
+ * Content Security Policy (hashes of the inline scripts, or a nonce
+ * placeholder), fonts that survive `font-src 'self'`, pdfkit's standard fonts, and a build that fails
+ * when the stylesheet is not wired. Everything is on; each part has an opt-out.
+ * Import it from the library: `import { nxgtMaterial } from '@nxgt/material/vite'`.
+ */
+export declare function nxgtMaterial(options?: NxgtMaterialOptions, library?: NxgtMaterialLibrary): Plugin[];
+//# sourceMappingURL=nxgt-material.d.ts.map

package/dist/vite/nxgt-material.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nxgt-material.d.ts","sourceRoot":"","sources":["../../src/vite/nxgt-material.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAKnC,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,KAAK,mBAAmB,EAAkB,MAAM,WAAW,CAAC;AAIrE;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC3B,OAAO,CAAC,EAAE,mBAAmB,EAC7B,OAAO,CAAC,EAAE,mBAAmB,GAC3B,MAAM,EAAE,CAmBV"}

package/dist/vite/options.d.ts

@@ -0,0 +1,56 @@
+import { type CspPolicyOptions } from '../csp';
+export type NxgtMaterialCspOptions = {
+    /**
+     * `'hash'` (default): the sha256 of every inline script and style of
+     * `index.html` goes to `dist/.vite/nxgt-csp.json`; nothing public is ever
+     * written into the HTML, so a static host is safe. `'nonce'`: the HTML
+     * carries a placeholder your server replaces per request (`applyCspNonce`).
+     */
+    mode?: 'hash' | 'nonce';
+    /** Nonce mode only: your own placeholder instead of `CSP_NONCE_PLACEHOLDER`. */
+    placeholder?: string;
+    /** An inline script that switches zod's `new Function` probe off. Default on. */
+    zodJitless?: boolean;
+    /** A `Content-Security-Policy-Report-Only` header on the dev server. Default on. */
+    dev?: boolean;
+    /** Refines the dev header and the generated one. */
+    policy?: CspPolicyOptions;
+};
+export type NxgtMaterialOptions = {
+    csp?: boolean | NxgtMaterialCspOptions;
+    fonts?: boolean | {
+        katex?: boolean;
+        sans?: 'inter' | false;
+    };
+    styles?: boolean | {
+        check?: boolean;
+    };
+    /**
+     * pdfkit's standard fonts (`pdfkitStandardFonts()`), on by default: it does
+     * nothing unless pdfkit goes through the bundle. `bundle: true` also puts
+     * the renderer into an SSR build (`ssr.noExternal`), for a server whose
+     * runtime image has no `node_modules`.
+     */
+    pdf?: boolean | {
+        bundle?: boolean;
+    };
+};
+export type ResolvedCsp = Required<Omit<NxgtMaterialCspOptions, 'policy'>> & {
+    policy: CspPolicyOptions;
+};
+export type ResolvedOptions = {
+    csp: false | ResolvedCsp;
+    fonts: {
+        katex: boolean;
+        sans: 'inter' | false;
+    };
+    styles: {
+        check: boolean;
+    };
+    pdf: false | {
+        bundle: boolean;
+    };
+};
+/** Booleans and objects normalised; everything is on by default. */
+export declare function resolveOptions(options?: NxgtMaterialOptions): ResolvedOptions;
+//# sourceMappingURL=options.d.ts.map

package/dist/vite/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/vite/options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAEtE,MAAM,MAAM,sBAAsB,GAAG;IACpC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACxB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,oFAAoF;IACpF,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,oDAAoD;IACpD,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IACjC,GAAG,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;IACvC,KAAK,CAAC,EAAE,OAAO,GAAG;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,GAAG,KAAK,CAAA;KAAE,CAAC;IAC9D,MAAM,CAAC,EAAE,OAAO,GAAG;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACvC;;;;;OAKG;IACH,GAAG,CAAC,EAAE,OAAO,GAAG;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,IAAI,CAAC,sBAAsB,EAAE,QAAQ,CAAC,CAAC,GAAG;IAC5E,MAAM,EAAE,gBAAgB,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC7B,GAAG,EAAE,KAAK,GAAG,WAAW,CAAC;IACzB,KAAK,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,OAAO,GAAG,KAAK,CAAA;KAAE,CAAC;IACjD,MAAM,EAAE;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IAC3B,GAAG,EAAE,KAAK,GAAG;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;CACjC,CAAC;AAEF,oEAAoE;AACpE,wBAAgB,cAAc,CAC7B,OAAO,GAAE,mBAAwB,GAC/B,eAAe,CA6BjB"}

package/dist/vite/pdf-plugin.d.ts

@@ -0,0 +1,19 @@
+import type { Plugin } from 'vite';
+import type { NxgtMaterialLibrary } from './libraries';
+/**
+ * What an SSR build must bundle for pdfkit's standard fonts to be rewritten
+ * and for the result to run with no `node_modules`: pdfkit (its
+ * `#standard-fonts/*` calls are what the transform rewrites), the renderer and
+ * the dependencies it needs at runtime (fontkit, yoga, png-js…), read from the
+ * installed packages so the list follows its releases. The library and core
+ * are named only, not walked. `react` is a peer and stays the app's to bundle.
+ * Under Yarn PnP there is no node_modules to read: only the fixed names apply.
+ */
+export declare function pdfNoExternal(root: string, library?: NxgtMaterialLibrary): (string | RegExp)[];
+/** Adds the packages above to `ssr.noExternal`; vite's merge keeps `true`. */
+export declare function pdfBundlePlugin(library?: NxgtMaterialLibrary): Plugin;
+/** The pdf part of `nxgtMaterial()`. */
+export declare function pdfPlugins(pdf: {
+    bundle: boolean;
+}, library?: NxgtMaterialLibrary): Plugin[];
+//# sourceMappingURL=pdf-plugin.d.ts.map

package/dist/vite/pdf-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pdf-plugin.d.ts","sourceRoot":"","sources":["../../src/vite/pdf-plugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAUvD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,mBAAmB,GAC3B,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAQrB;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAUrE;AAED,wCAAwC;AACxC,wBAAgB,UAAU,CACzB,GAAG,EAAE;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,EACxB,OAAO,CAAC,EAAE,mBAAmB,GAC3B,MAAM,EAAE,CAKV"}

package/dist/vite/pdfkit-standard-fonts.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The pdfkit standard fonts plugin of the `/vite` entry (Node code that runs
+ * inside a consumer's `vite.config.ts` or a Nuxt app's Nitro build). It
+ * imports nothing at runtime: `Plugin` is a type, erased by the compiler.
+ */
+import type { Plugin } from 'vite';
+/**
+ * Bundles pdfkit's fourteen standard fonts instead of leaving them to a
+ * `require` that cannot work in a bundle.
+ *
+ * **Only needed by an app that renders PDFs** (`@nxgt/material/print`, or
+ * `@nxgt/material-vue/pdf`). No other entry reaches `@react-pdf/renderer`, so
+ * an app that does not print never sees this at all.
+ * If you do print, read on, because the failure is spectacular and silent until
+ * production.
+ *
+ * Both are built on `@react-pdf/renderer`, which is built on
+ * `pdfkit`, whose node build ends with:
+ *
+ * ```js
+ * const require$1 = createRequire(import.meta.url);
+ * registerStdFontLoaders({ Helvetica: () => require$1('#standard-fonts/Helvetica'), … });
+ * ```
+ *
+ * `#standard-fonts/*` is a package-`imports` entry **private to pdfkit**, and
+ * that is a RUNTIME call, not an import — so no bundler resolves it. Bundle
+ * pdfkit into an SSR server (`ssr.noExternal`) and the literal survives into the
+ * output, where `createRequire` is rooted at the build directory and the importer
+ * is no longer inside pdfkit. The server then throws on **every request**,
+ * `/health` included:
+ *
+ * ```
+ * error: Cannot find module '#standard-fonts/Helvetica' from '…/build/app.js'
+ * ```
+ *
+ * A compose healthcheck that fetches a route never goes healthy either, so the
+ * container looks like it is failing to start rather than failing to serve.
+ *
+ * This plugin rewrites those calls into static imports of
+ * `./standard-fonts/<name>.mjs`, so the font data lands in the bundle and the
+ * server stays self-contained. Use it when the runtime image has **no
+ * `node_modules`** — a single-file `bun build` artifact copied alone into the
+ * image. When the image does keep `node_modules`, the lighter answer is to leave
+ * the library external instead (`--external` it in the bundle step, and keep it
+ * out of `ssr.noExternal`), which also keeps ~12 MB of
+ * pdfkit out of the artifact. `nxgtMaterial({ pdf: { bundle: true } })` adds this
+ * plugin and the `ssr.noExternal` list it needs; in Nuxt, `nxgtMaterial: { pdf: {
+ * bundle: true } }` adds this plugin to the Nitro build.
+ *
+ * ```ts
+ * // `@nxgt/material/vite` in a React app: the same function
+ * import { pdfkitStandardFonts } from '@nxgt/material-vue/vite';
+ * import { defineConfig } from 'vite';
+ *
+ * export default defineConfig({
+ *   plugins: [pdfkitStandardFonts()],
+ *   ssr: { noExternal: ['@nxgt/material-vue', '@nxgt/material-core'] },
+ * });
+ * ```
+ *
+ * Two things that look like fixes and are not:
+ *
+ * - **`resolve.alias`** mapping `#standard-fonts/` to `pdfkit/standard-fonts/`.
+ *   An alias rewrites specifiers the resolver is *asked* about; this one is a
+ *   string handed to `createRequire` at runtime, which the resolver never sees.
+ * - **`--external pdfkit`**. It is a transitive dependency, so the runtime cannot
+ *   resolve it from the app's own directory: `Cannot find package 'pdfkit'`.
+ *
+ * The plugin throws if a `#standard-fonts/` reference survives the rewrite, so a
+ * future pdfkit that changes the shape of those calls fails the build instead of
+ * the first request.
+ */
+export declare function pdfkitStandardFonts(): Plugin;
+//# sourceMappingURL=pdfkit-standard-fonts.d.ts.map

package/dist/vite/pdfkit-standard-fonts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pdfkit-standard-fonts.d.ts","sourceRoot":"","sources":["../../src/vite/pdfkit-standard-fonts.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CA6C5C"}

package/dist/vite/styles-plugin.d.ts

@@ -0,0 +1,27 @@
+import type { Plugin } from 'vite';
+import type { LibraryDescriptor } from './libraries';
+/** What the build saw of the library's stylesheet; shared with the fonts part. */
+export type StylesState = {
+    /** The stylesheets (ids) that import the library's `styles.css` (Tailwind's route). */
+    roots: Set<string>;
+    /**
+     * The stylesheets that `@import` the package itself: its root export's
+     * `style` condition, the compiled stylesheet of an app without Tailwind,
+     * which needs no `@source`.
+     */
+    compiledRoots: Set<string>;
+    /** Modules that import it from JavaScript. */
+    jsImporters: Set<string>;
+    sourceOk: boolean;
+};
+export declare function createStylesState(): StylesState;
+export declare function missingStylesheetMessage(lib: LibraryDescriptor): string;
+export declare function missingSourceMessage(lib: LibraryDescriptor): string;
+/**
+ * Fails a client `vite build` that never imports the library's stylesheet
+ * (`styles.css`, or the compiled one through `@import "<package>";`), or
+ * (React) imports `styles.css` without the `@source` line. `order: 'pre'` makes it see
+ * the raw stylesheet before `@tailwindcss/vite` rewrites it.
+ */
+export declare function stylesPlugin(lib: LibraryDescriptor, state: StylesState): Plugin;
+//# sourceMappingURL=styles-plugin.d.ts.map

package/dist/vite/styles-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles-plugin.d.ts","sourceRoot":"","sources":["../../src/vite/styles-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAMrD,kFAAkF;AAClF,MAAM,MAAM,WAAW,GAAG;IACzB,uFAAuF;IACvF,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnB;;;;OAIG;IACH,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,8CAA8C;IAC9C,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,wBAAgB,iBAAiB,IAAI,WAAW,CAO/C;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAMvE;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAMnE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC3B,GAAG,EAAE,iBAAiB,EACtB,KAAK,EAAE,WAAW,GAChB,MAAM,CA0CR"}

package/dist/vite/styles-scan.d.ts

@@ -0,0 +1,14 @@
+/** Pure scans of a stylesheet's text. */
+/** The specifiers of every `@import` (both quote styles, `url()`), comments skipped. */
+export declare function cssImports(css: string): string[];
+/** The paths of every plain `@source` (`not` and `inline()` forms add nothing to scan). */
+export declare function cssSources(css: string): string[];
+/** The `@import`s that point at a file next to the stylesheet. */
+export declare function relativeImports(css: string): string[];
+/** Whether a `@source` path points at the package (`…/node_modules/@nxgt/material/`). */
+export declare function sourceCovers(path: string, name: string): boolean;
+/** Whether a module's code imports `specifier` (static or dynamic, any quotes). */
+export declare function jsImports(code: string, specifier: string): boolean;
+/** Whether the stylesheet sets Tailwind's `--font-sans` itself. */
+export declare function declaresFontSans(css: string): boolean;
+//# sourceMappingURL=styles-scan.d.ts.map

package/dist/vite/styles-scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles-scan.d.ts","sourceRoot":"","sources":["../../src/vite/styles-scan.ts"],"names":[],"mappings":"AAAA,yCAAyC;AASzC,wFAAwF;AACxF,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAIhD;AAED,2FAA2F;AAC3F,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAEhD;AAED,kEAAkE;AAClE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAErD;AAED,yFAAyF;AACzF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAGhE;AAED,mFAAmF;AACnF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAKlE;AAED,mEAAmE;AACnE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAErD"}

package/docs/README.md

@@ -5,5 +5,9 @@ one example per subpath.
 
 | Page | Read it when |
 | --- | --- |
+| [Backgrounds](backgrounds.md) | you build a background preset, or render a scene a preset produced |
 | [Troubleshooting](troubleshooting.md) | an import, a render or a build fails with a message: the message is the heading |
 | [Roadmap](roadmap.md) | you want to know what is coming, or whether something was already ruled out |
+| [States](states.md) | you build on `/states`: the kinds, the copy keys, `describeError` or the illustrations' geometry |
+
+The `/csp` subpath (the Content Security Policy for a server or a build) is documented in the [README](../README.md#the-csp-for-a-server-or-a-build-csp).

package/docs/backgrounds.md

@@ -0,0 +1,95 @@
+# Backgrounds (`@nxgt/material-core/backgrounds`)
+
+The engine under the background presets of `@nxgt/material` and
+`@nxgt/material-vue`. Use it to build a preset of your own, or to read what a
+preset produces. Most apps use a library's `Background` component instead.
+
+## The scene
+
+A background's SVG is a plain tree, not a string:
+
+```ts
+interface SceneNode {
+	tag: SceneTag; // svg g path circle rect ellipse line polygon defs pattern
+	// linearGradient radialGradient stop filter feTurbulence feColorMatrix
+	// feGaussianBlur mask
+	attrs: Readonly<Record<string, string | number>>;
+	children?: readonly SceneNode[];
+}
+```
+
+A library renders it with `createElement` (React) or `h` (Vue), so no
+`dangerouslySetInnerHTML` or `v-html`. `el(tag, attrs, children)` builds a
+node.
+
+### What a scene may hold
+
+Geometry and presentation attributes only (`SCENE_ATTRIBUTES`). `assertSafeScene(scene, idPrefix?)`
+throws, naming the path (`svg>g>rect`), for:
+
+- `style`, any `on*` handler, `href`, `xlink:href`, or any attribute not on the list;
+- a URL (`javascript:`, `data:`, `http:`...) in a value, or a `url(...)` that is not `url(#id)` with
+  the id of an element **in the same scene**;
+- an id or class with characters outside `A-Z a-z 0-9 _ -`, markup in a value, a number that is not finite;
+- with `idPrefix`, an id that does not start with `<idPrefix>-`.
+
+This is what keeps a background working under a strict Content Security Policy:
+a `style` attribute in server-rendered HTML needs `style-src-attr 'unsafe-inline'`.
+Colour an element with a class (`class: 'k1'` and a `color` rule in CSS, drawn with
+`currentColor`), and spread durations or drift vectors over class buckets.
+
+## Determinism
+
+`mulberry32(seed)` returns a generator in [0, 1). `scatter`, `valueNoise2` and the
+builders draw from it, so the same `seed` gives the same scene on the server and
+the client and hydration finds no mismatch. The folder has no `Math.random` and
+reads no clock (a repository spec checks). The geometry uses a fixed
+`1600 x 1000` box that the SVG scales with `preserveAspectRatio="xMidYMid slice"`.
+
+- `scatter(rand, sizes, { gap, pad, margin, attempts })`: variable-radius dart throwing, largest first; a size that finds
+  no room in `attempts` tries is dropped.
+- `valueNoise2(rand, lx, ly, width, height)`: smooth noise in [0, 1] over a box.
+- `motifShape(shape, halfSize, filled)` draws one of `MOTIF_SHAPES` (`circle`, `ring`,
+  `square`, `triangle`, `plus`, `line`, `arc`) in `currentColor`; `place({ x, y, rotation, className, opacity }, node)`
+  puts it somewhere.
+- `MOTIF_DEFAULTS`: every shape, `density: 'default'`, `size: 'mixed'`, `rotate: true`,
+  `shapeFill: 'mixed'`, `opacitySpread: 'varied'`.
+
+## Ids
+
+An id inside `url(#...)` may not hold the characters React's `useId` produces (`:r1:`, `«r1»`).
+`svgIdPrefix(useId())` returns `bg-r1`; name ids `${prefix}-grain` and so on, and every
+scene on a page stays unique.
+
+## Pausing an animation
+
+`observeBackgroundActivity(element, onChange)` calls `onChange(paused)` once, then when
+it changes: `paused` is true while the page is hidden, the element is off screen
+(`IntersectionObserver`), or `prefers-reduced-motion: reduce` matches. It returns the
+function that removes everything. It reads the DOM only when called, so call it from an effect
+(`useEffect`, `onMounted`) and only for an animated background.
+
+## The preset table
+
+`BACKGROUND_PRESETS` lists the 20 ids in three families (`light`, `geometry`, `motif`) with
+`kind` (`css`, `svg`, `css+svg`), `seeded` and the `motifControls` each reads. The ids are
+final; the other columns follow how each preset ends up drawn.
+`buildBackgroundScene(preset, { idPrefix, seed })` returns a preset's scene (checked with
+`assertSafeScene`) or `null` when it is CSS-only or its builder is not there yet. Only
+`grain` has one so far.
+
+`SHIPPED_BACKGROUND_PRESETS` (`'gradient' | 'grain'`, type `ShippedBackgroundPreset`) is the
+subset the libraries draw today; it widens as presets land. `resolveShippedPreset(id)` returns
+`id` when it ships and `'gradient'` otherwise, with a one-time `console.warn` outside production.
+
+## The grain
+
+`buildGrain` (also `buildBackgroundScene('grain', ...)`) is a film-noise overlay: an `feTurbulence`
+filter, turned grey, drawn on one rect. The filter id is `<idPrefix>-noise` and `seed` moves the noise.
+
+```ts
+import { buildBackgroundScene, svgIdPrefix } from '@nxgt/material-core/backgrounds';
+
+const scene = buildBackgroundScene('grain', { idPrefix: svgIdPrefix(id), seed: 3 });
+```
+

package/docs/roadmap.md

@@ -10,29 +10,10 @@ Nothing is in progress.
 
 ## Next
 
-- **One Vite plugin for the whole setup** — `nxgtMaterial()` is implemented
-  once in `/vite` and re-exported by `@nxgt/material/vite` and
-  `@nxgt/material-vue/vite`, so both libraries get the same one-call setup.
-  Every option is on by default and each can be turned off or refined; the
-  helpers that exist today (`cspAssetsInlineLimit` and the others) stay
-  exported.
-  - `csp`: a nonce placeholder through `html.cspNonce` and
-    `applyCspNonce(html, nonce)`; zod's jitless mode as an inline nonced
-    script in `index.html` (`ZOD_JITLESS_SCRIPT` for server rendering); the
-    recommended policy sent by the dev server as Report-Only.
-  - `fonts`: the KaTeX fonts emitted as files, and `sans: 'inter'` for a
-    self-hosted Inter.
-  - `styles`: a build that fails with the exact fix when the stylesheet import
-    or the `@source` line is missing.
-  - `pdf`: pdfkit's standard fonts handled automatically when
-    `@react-pdf/renderer` is installed, and `bundle: true` (the Nuxt module's
-    `pdf.bundleStandardFonts` today) for a server that has no
-    `node_modules`.
-  - Nuxt: the Nuxt module takes the same options.
-  - Server helpers: `createCspNonce()` (Web Crypto) and `cspPolicy({ ... })`,
-    which returns `{ directives, header }` as `@nxgt/material`'s
-    Content Security Policy guide describes; `NonceProvider`'s `nonce`
-    becomes optional on the client. Ships as minors.
+- **More background presets** — the rest of the planned presets (see
+  `BACKGROUND_PRESETS`: meshes, aurora, topography, shapes, constellation, ...)
+  as scene builders registered in `buildBackgroundScene`. Until one ships,
+  `resolveShippedPreset` falls back to the gradient.
 - **The shared media player** — the player state machine (playback, queue and
   shuffle, chapters, transcript sync, resume position, quality levels, Wake
   Lock), its keyboard shortcuts and the shortcut-help list, so
@@ -76,6 +57,39 @@ Nothing is in progress.
 
 ## Shipped
 
+- **The background presets' engine** (`/backgrounds`) — a seeded generator,
+  value noise, scattering, motif shapes, a plain SVG scene format with
+  `assertSafeScene` (safe under a strict CSP), ids for `url(#…)`, the observer
+  that pauses an animation, and the first builder, `buildGrain`. Behind both
+  libraries' `Background` on `/backgrounds`.
+
+- **One Vite plugin for the whole setup** — `nxgtMaterial()` from
+  `@nxgt/material/vite` and `@nxgt/material-vue/vite` (one implementation in
+  `@nxgt/material-core/vite`) wires the library into a Vite app, each part on
+  by default and each switchable off; the helpers that existed before stay
+  exported ([Vite plugin guide](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/vite-plugin.md)). You get:
+  - `csp`: `mode: 'hash'` (default) writes the sha256 of every inline script
+    and style to `dist/.vite/nxgt-csp.json` with the header, or `mode: 'nonce'`
+    leaves a placeholder for `applyCspNonce`; zod's jitless script; a
+    Report-Only header on the dev server. `createCspNonce()`, `cspPolicy()`
+    and `cspHash()` ship in `@nxgt/material-core/csp`.
+  - `fonts`: `katex` (fonts stay files) and `sans: 'inter'` (self-hosted Inter).
+  - `styles`: a build that fails with the exact fix when the stylesheet import
+    or React's `@source` line is missing.
+  - `pdf`: pdfkit's standard fonts handled by the same plugin, with
+    `bundle: true` for an SSR server with no `node_modules`. The Nuxt module
+    calls `nxgtMaterial()` with the same `fonts`, `styles` and `pdf` options
+    (`pdf.bundleStandardFonts` is deprecated for `pdf.bundle`) and adds zod's
+    jitless script to the head on request; its CSP stays `nuxt-security`'s.
+  - `NonceProvider`'s `nonce` is optional on the client (a client-only app gets the
+    page's nonce from its first render; a hydrated app passes it on both sides).
+  Shipped in 0.13.0.
+- **The room above a Drawer's footer** (`/drawer-room`) — the height an open
+  floating list may take inside a Drawer without covering its footer, behind
+  both libraries' `Autocomplete`.
+- **An avatar's initials** (`/initials`) — the first letter of a name's
+  first and last word, upper-cased and never cut inside a character, behind
+  both libraries' `AccountMenu`.
 - **A repeatable row group's focus rules** (`/repeatable-group`) — where the
   focus goes after a row is added, removed or moved, the add and remove
   limits, and what the live region announces, behind both libraries'

package/docs/states.md

@@ -0,0 +1,85 @@
+# States: `/states`
+
+The framework-free half of `EmptyState` and `ErrorState`: which kinds exist,
+where their text lives, what of an error may be shown, and the geometry of
+their illustrations. Nothing runs at import, so it is safe on a server. The
+README has the one-line example; this page has the detail.
+
+## Kinds
+
+| Family | Kinds | Meaning |
+| --- | --- | --- |
+| Empty | `empty`, `search`, `not-found`, `unauthorized` | an absence: nothing yet, nothing found, no such page, no access |
+| Error | `generic`, `offline`, `maintenance` | something failed |
+
+`resolveEmptyStateKind({ kind, variant })` returns `kind`, else the legacy
+`variant` (all seven values), else `'generic'`, the default `EmptyState` has
+always had. `isErrorKind(kind)` tells the families apart.
+
+```ts
+import { isErrorKind, resolveEmptyStateKind } from '@nxgt/material-core/states';
+
+resolveEmptyStateKind({}); // 'generic'
+resolveEmptyStateKind({ variant: 'offline' }); // 'offline'
+resolveEmptyStateKind({ kind: 'search', variant: 'offline' }); // 'search'
+isErrorKind('offline'); // true
+```
+
+## Copy
+
+`stateCopy(kind, family)` returns `{ titleKey, descriptionKey, title,
+description }`: the i18n keys and their English fallbacks.
+
+- `'empty-state'` reads `material.empty-state.<kind>.*`, for all seven kinds
+  (so an app that overrides `material.empty-state.generic.title` keeps its
+  text on an `EmptyState` given a legacy error `variant`).
+- `'error-state'` reads `material.error-state.<kind>.*` for the three error
+  kinds; any other kind falls back to `material.empty-state.*`.
+
+`STATE_ACTION_KEYS` holds the keys of `ErrorState`'s Retry button and details
+(`retry`, `details`, `detailsName`, `detailsMessage`, `detailsCause`), each
+with its English fallback. An app that overrode `material.empty-state.generic|
+offline|maintenance.*` must override the `material.error-state.*` keys too.
+
+```ts
+import { stateCopy } from '@nxgt/material-core/states';
+
+const { titleKey, title } = stateCopy('offline', 'error-state');
+t(titleKey, title); // 'material.error-state.offline.title', 'You are offline'
+```
+
+## Error details
+
+`describeError(error, { maxDepth })` returns `{ name, message }` for the
+error, then for each `cause`, at most `maxDepth` entries (3 by default). It
+takes an `Error`, a `{ message }` object, a string or any primitive; stops at
+a cycle; returns `[]` for `null` and `undefined`; and does not throw on a
+hostile getter. It **never reads `.stack`**: a stack names files and paths.
+
+```ts
+import { describeError } from '@nxgt/material-core/states';
+
+describeError(new Error('Could not save', { cause: new TypeError('Failed to fetch') }));
+// [{ name: 'Error', message: 'Could not save' },
+//  { name: 'TypeError', message: 'Failed to fetch' }]
+```
+
+## Illustrations
+
+`STATE_ILLUSTRATIONS[kind]` is `{ viewBox, shapes }`. A shape is `{ el, tone,
+attrs }`: `el` is `path`, `circle`, `rect`, `ellipse` or `line`; `attrs` are
+single-word SVG attributes (`d`, `cx`, `rx`, `transform`…); `tone` is
+`surface`, `outline`, `accent`, `accent-soft` or `muted`. There is no colour
+and no style in the data: a library maps the tone, and the kind's
+`STATE_ACCENT` (`primary`, `error`, `warning`, `info`, `neutral`), to classes
+on its theme tokens, so the SVG is CSP-safe. `STATE_ICON[kind]` is the kind's
+lucide icon, in kebab-case.
+
+```tsx
+import { STATE_ILLUSTRATIONS } from '@nxgt/material-core/states';
+
+const { viewBox, shapes } = STATE_ILLUSTRATIONS['not-found'];
+<svg viewBox={viewBox} aria-hidden="true">
+	{shapes.map((s, i) => createElement(s.el, { key: i, className: toneClass(s.tone), ...s.attrs }))}
+</svg>;
+```