@nxgt/material-core 0.15.0-next-20261013091433 → 0.15.0

package/CHANGELOG.md

@@ -1,16 +1,14 @@
 # @nxgt/material-core
 
-## 0.15.0-next-20261013091433
+## 0.15.0
 
 ### Minor Changes
 
-- [#693](https://github.com/softistx/nxgt-material/pull/693) [`075693d`](https://github.com/softistx/nxgt-material/commit/075693dda8355458d3a2795277bfba0de14a773b) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `@nxgt/material-core/data-grid`: the pure half of the coming editable `DataGrid` — its model (rows and columns by position and key, what each cell allows, the version each cell was read from, per cell with the row's as the fallback), navigation and keyboard commands (arrows over the header, body and footer rows, Home/End and Ctrl/Cmd+Left/Right, Ctrl/Cmd+Up/Down to a column's ends, Ctrl/Cmd+Home/End, PageUp/PageDown, Tab and Enter skipping cells that cannot be edited, RTL), the selected range, the edit session, validation (a column's parse, then `validate`, then any Standard Schema; the server's refusals by entry index), a number column with codes (`numberCodes`: "abs" or "disp" in any language, `,` or `.` as the decimal separator, bounds and decimals, an empty text clearing the cell) and the live region's message descriptors.
+- [#803](https://github.com/softistx/nxgt-material/pull/803) [`51244b0`](https://github.com/softistx/nxgt-material/commit/51244b06a7036d5f4e8d5d237cd27dc662bcb447) Thanks [@SteveGT96](https://github.com/SteveGT96)! - Backgrounds: all twenty presets are drawn. `buildBackgroundScene` now draws the light presets (`mesh`, `aurora`, `spotlight`, `bokeh`), the geometry presets (`isometric`, `blueprint`, `dots`, `stripes`, `low-poly`, `topography`, `waves`) and the motif presets (`shapes`, `confetti-grid`, `constellation`, `halftone`, `truchet`, `floating`, `scatter-icons`), each seeded where it has geometry. `buildBackgroundScene` is the one public way to draw them: the per-preset builders stay internal (`buildGrain`, already published, stays exported). `presetLayers(preset)` gives a preset's `data-layer` names in paint order, with `SCENE_LAYER` marking where its SVG goes, from a table that holds no builder. `resolveBackgroundPreset(id, available)` resolves an id against a library's own list (`resolveShippedPreset` stays, over `SHIPPED_BACKGROUND_PRESETS`). A scene may use `stop-opacity` on a gradient stop, and a motif's drift is classes (`fl`, `v1..v8`, `d1..d6`, `l1..l4`), never an inline `style`. The grain scene is final: black specks from an alpha noise, sized in screen pixels.
   
-  `@nxgt/material-core/parse-number`: `parseNumberInput`, `clampNumber` and `stepNumber` move here from `@nxgt/material`'s `NumberField`, plus `decimalsTyped`; they read a number as `NumberField` does, directional marks skipped and `−` as a minus.
-
-- [#699](https://github.com/softistx/nxgt-material/pull/699) [`b13f08a`](https://github.com/softistx/nxgt-material/commit/b13f08a5c1a92f362ecd4e1f365173b5a8eb88f6) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `@nxgt/material-core/data-grid`: the rest of the coming editable `DataGrid`'s pure half — the changes per cell (`editCell`, each change keeping the value and the version it was read at, per cell with the row's as the fallback; `rebase` after a refetch, a moved version and value turning a pending edit into a conflict while a cell whose value is still its base adopts the new version; a saved value, and "Keep theirs", kept as an overlay until the app's rows hold it, a refetch still read at the version a save or a conflict replaced changing nothing; `resolveConflict` with "theirs" or "mine"; a conflict outliving any edit until it is resolved; `expireSaved`; `changeCounts` and `blocking`), the save queue (`startCall`, `applyAnswer`, `applyFailure`, `applyAbort`, `retry`: one call in flight at a time; per cell up to 200 entries a call, per row once the row is left, or in one batch on `save()` with no limit, blocked while a cell is in error or in conflict; an answer is all or nothing, `versions[i]` updating entry `i`'s cells (and, with `versionScope: 'row'`, the row's other changes) and a refusal flagging its cells as errors or conflicts; paused after 3 failures in a row, an abort counting none), undo and redo (`record`, `undo`, `redo`: 100 steps, an undo is a new edit, cells changed since are skipped and counted), tab-separated copy and paste as Excel and Google Sheets write it, a cell with a quote and no line break read raw (`parseTsv`, `serializeTsv`), the all-or-nothing paste plan (`planPaste`: past the grid, locked, read-only, computed, not parsed and invalid cells listed as problems), the totals' aggregates (`aggregate`: sum, mean, min, max, count, or the app's own, over numbers only; a count of nothing is 0), the sort order kept while editing (`reconcileOrder`) and the conflict panel's two values, a cleared one reading "Cleared" (`conflictValues`).
-
-- [#769](https://github.com/softistx/nxgt-material/pull/769) [`8e4cdfa`](https://github.com/softistx/nxgt-material/commit/8e4cdfae4d67d6563f916e35112cadac8d54e2ce) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `@nxgt/material-core/escape-forward`: a control marked `data-keeps-escape` keeps Escape from the Dialog, Sheet, Drawer, AlertDialog or Popover around it (in both libraries), as a field whose list is open does; `isKeptEscape(event)` tells such an Escape from one the page prevented.
+  The motif options (`MotifOptions`: `shapes`, `density`, `size`, `rotate`, `shapeFill`, `opacitySpread`) drive the motif presets. **`MOTIF_DEFAULTS.rotate` is now `false`** (it was `true`): motifs stay upright unless `rotate` is set.
+  
+  Tree-shaking: importing one name from `@nxgt/material-core/backgrounds` (`presetLayers`, `svgIdPrefix`, `buildGrain`, …) no longer bundles every preset's builder.
 
 ## 0.14.0
 

package/README.md

@@ -10,8 +10,8 @@ the date range presets, a debounce, accent-insensitive text matching and a race-
 rule, a field's first reachable control (`/focus-control`) and its `aria-describedby`
 (`/described-by`), where the focus goes in a repeatable row group
 (`/repeatable-group`), the page behind a modal layer made inert
-(`/inert-others`), Escape pressed while an overlay closes, in a field whose
-list is open or in a control marked `data-keeps-escape` (`/escape-forward`), the Toaster's guard against a tap's emulated hover
+(`/inert-others`), Escape pressed while an overlay closes or in a field whose
+list is open (`/escape-forward`), the Toaster's guard against a tap's emulated hover
 (`/touch-hover`), the focus a toast's action hands back (`/toast-focus`), a
 table row's activation, the zod error map's issue messages
 (`/zod-issue-messages`), a zod error map that words an issue by its code
@@ -30,8 +30,7 @@ re-export what they always exported, at the same subpaths:
 from here, and so do their `PdfReader`, `CurrencyField`, form fields (their
 focus, blur, `aria-describedby` and zod messages), file list and upload
 field (`formatFileSize`), modal layers (the inert page behind, Escape while
-closing, Escape in a field whose list is open or in a control marked
-`data-keeps-escape`), `Toaster`, `DataTable` rows, `@nxgt/material/next` and
+closing, Escape in a field whose list is open), `Toaster`, `DataTable` rows, `@nxgt/material/next` and
 `@nxgt/material-vue/nuxt`. Import it directly when you want the model or a
 formatter without a UI library, or one of these helpers in a component of
 your own.
@@ -93,10 +92,10 @@ can reach. No other subpath imports a `node:` built-in.
 | `/field-blur-layers` | `layerOf`, `openerOf`, `FieldLayers` — whose overlay a layer of the page is, for a field's blur |
 | `/focus-control` | `firstControl`, `focusHandle`, `FocusHandle` — the first control of a field a user can reach, and a stand-in element that focuses it for a form library |
 | `/repeatable-group` | `focusAfterRemove`, `focusAfterMove`, `focusRowTarget`, `rowMoveTarget`, `canAddRow`, `canRemoveRow`, `RowFocusTarget`, `RowMoveDirection`, `RowAnnouncement`, `ROW_SLOT`, `ROW_FIELDS_SLOT`, `ADD_ATTRIBUTE` — where the focus goes after a row of a `RepeatableGroup` is added, removed or moved, and what its live region says |
-| `/escape-forward` | `forwardEscape`, `keepListEscape`, `isKeptEscape` — Escape pressed while an overlay closes, pressed again for the overlay below once it has gone; Escape pressed in a field whose list is open, or in a control marked `data-keeps-escape`, kept from closing the overlay around it, and told from an Escape the page prevented |
+| `/escape-forward` | `forwardEscape`, `keepListEscape` — Escape pressed while an overlay closes, pressed again for the overlay below once it has gone; Escape pressed in a field whose list is open, kept from closing the overlay around it |
 | `/described-by` | `describedBy` — an `aria-describedby` value from the caller's ids and a field's help and error ids |
 | `/inert-others` | `inertOthers`, `INERT_MARKER` — the rest of the page `inert` behind a modal layer, live regions kept, nested layers counted |
-| `/backgrounds` | `buildBackgroundScene`, `buildGrain`, `assertSafeScene`, `svgIdPrefix`, `observeBackgroundActivity`, `mulberry32`, `valueNoise2`, `scatter`, `motifShape`, `place`, `BACKGROUND_PRESETS`, `SHIPPED_BACKGROUND_PRESETS`, `resolveShippedPreset`, `BACKGROUND_TONES`, `MOTIF_SHAPES`, `MOTIF_DEFAULTS` and the types `BackgroundPreset`, `ShippedBackgroundPreset`, `BackgroundTone`, `BackgroundIntensity`, `MotifOptions`, `SceneNode`, `PresetInfo` — the engine behind the libraries' background presets: a seeded generator, scattering, motif shapes, a plain SVG scene format with its safety check, ids for `url(#…)`, and the observer that pauses an animation |
+| `/backgrounds` | `buildBackgroundScene`, `buildGrain`, `assertSafeScene`, `el`, `SCENE_ATTRIBUTES`, `SCENE_TAGS`, `svgIdPrefix`, `observeBackgroundActivity`, `mulberry32`, `pick`, `round1`, `valueNoise2`, `scatter`, `motifShape`, `place`, `BACKGROUND_PRESETS`, `SHIPPED_BACKGROUND_PRESETS`, `resolveBackgroundPreset`, `resolveShippedPreset`, `presetLayers`, `SCENE_LAYER`, `BACKGROUND_TONES`, `BACKGROUND_INTENSITIES`, `MOTIF_SHAPES`, `MOTIF_DEFAULTS`, and the types `BackgroundPreset`, `ShippedBackgroundPreset`, `BackgroundTone`, `BackgroundIntensity`, `MotifDensity`, `MotifShape`, `MotifSize`, `OpacitySpread`, `ShapeFill`, `SceneBuilder`, `SceneOptions`, `SceneTag`, `ScatterOptions`, `ScatterPoint`, `PlaceOptions`, `MotifOptions`, `SceneNode`, `PresetInfo` — the engine behind the libraries' background presets: a seeded generator, scattering, motif shapes, a plain SVG scene format with its safety check, ids for `url(#…)`, and the observer that pauses an animation |
 | `/touch-hover` | `ignoreTouchHover`, `TOASTER_PHONE_QUERY`, `TOASTER_PHONE_POSITION` — keeps a tap from hovering an element, so a toast a finger touched does not stay paused; where the `Toaster` puts toasts on a phone |
 | `/toast-focus` | `focusOrigin`, `handFocusBack`, `trackToasterOrigin`, `TOASTER_SELECTOR` — where the focus was before it entered a toast, and handing it back there before the toast's action runs, so a dialog the action opens keeps the focus |
 | `/zod-issue-messages` | `sizeMessage`, `invalidFormatMessage`, `IssueText` — the translated text of a zod `too_big` / `too_small` and `invalid_format` issue |
@@ -121,8 +120,6 @@ can reach. No other subpath imports a `node:` built-in.
 | `/states` | `EMPTY_STATE_KINDS`, `ERROR_STATE_KINDS`, `resolveEmptyStateKind`, `isErrorKind`, `stateCopy`, `STATE_ACTION_KEYS`, `describeError`, `STATE_ILLUSTRATIONS`, `STATE_ACCENT`, `STATE_ICON` and the types `EmptyStateKind`, `ErrorStateKind`, `StateKind`, `LegacyEmptyStateVariant`, `StateFamily`, `StateCopy`, `ErrorDetail`, `StateIllustration`, `IllustrationShape`, `IllustrationTone`, `StateAccent`, `StateIconName` — the kinds, copy keys, error details and illustrations behind `EmptyState` and `ErrorState` |
 | `/vite` | `nxgtMaterial()`, `pdfkitStandardFonts()`, `cspAssetsInlineLimit`, `CSP_NONCE_PLACEHOLDER`, `ZOD_JITLESS_SCRIPT` and the types `NxgtMaterialOptions`, `NxgtMaterialCspOptions`, `NxgtMaterialLibrary` — see below |
 | `/pdfkit-fonts` | **Node only.** `pdfkitStandardFontDirs`, `pdfkitStandardFontFiles`, `PDFKIT_STANDARD_FONTS`, the types `PdfkitStandardFont` and `PdfkitFontsWarn` — where the app's pdfkit keeps its standard fonts, for a server tracer |
-| `/data-grid` | **Headless**, for the editable `DataGrid` coming in `@nxgt/material`; nothing renders yet. The model (`buildGridModel`, `cellAccess`, `cellVersion` and `isNewCellVersion`), navigation (`navigate`, `gridCommandFor`), the range (`extend`, `selectAll`, `rangeCells`, …), the edit session (`editReducer`), validation (`validateCell`, `serverErrors`, `refusalsByCell`, Standard Schema), `numberCodes`, the changes per cell (`NO_CHANGES`, `editCell`, `rebase`, `resolveConflict`, `expireSaved`, `changeCounts`, `blocking`), the save queue (`IDLE_QUEUE`, `nextCall`, `startCall`, `applyAnswer`, `applyFailure`, `applyAbort`, `retry`), undo and redo (`EMPTY_HISTORY`, `record`, `undo`, `redo`), copy and paste (`parseTsv`, `serializeTsv`, `planPaste`), the totals (`aggregate`), the kept sort order (`snapshotOrder`, `reconcileOrder`, `sortingChanged`), the conflict panel's text (`conflictValues`, `conflictSummary`, `clearedText`) and the live region's descriptors (`savedMessage`, `cellStateText`, …), with the types `GridModel`, `GridColumnSpec`, `GridRowSpec`, `GridMsg`, `GridPos`, `GridRange`, `GridVersion`, `GridCode`, `GridChanges`, `GridSaveQueue`, `GridCall`, `GridSaveAnswer`, `GridHistory`, `GridStep`, `GridPasteInput`, `GridPastePlan`, `GridPasteProblem`, `GridAggregate` and `GridSort`. A cell's version is `0` or `undefined` when it does not exist yet on the server. See below |
-| `/parse-number` | `parseNumberInput`, `decimalsTyped`, `clampNumber`, `stepNumber` — a typed number read with `,` or `.` as its decimal separator, its typed decimals, and the clamp and step behind `NumberField` |
 
 ## Usage
 
@@ -1082,30 +1079,6 @@ list sits in a `[data-slot="combobox-content"]` popup (a command palette's
 input is not), or when it carries `data-list-open="true"` (the Vue
 `Autocomplete`'s textbox).
 
-A control that handles Escape itself (a grid's cell editor, whose Escape
-cancels the edit; a grid cell whose Escape collapses a selected range)
-carries `data-keeps-escape`, or sits inside an element that does (a grid's
-paste-problems panel, whose Escape closes it): `keepListEscape` keeps its
-Escape from the overlay around it too. Its own handler then sees `defaultPrevented` true,
-for an Escape that is still its own: `isKeptEscape(event)` is `true` for an
-Escape `keepListEscape` kept (and only for one), so the handler can tell it
-from an Escape something else prevented.
-
-```tsx
-import { isKeptEscape } from '@nxgt/material-core/escape-forward';
-
-declare function cancelEdit(): void;
-
-<input
-  data-keeps-escape=""
-  onKeyDown={(event) => {
-    const native = event.nativeEvent;
-    if (event.defaultPrevented && !isKeptEscape(native)) return;
-    if (event.key === 'Escape') cancelEdit(); // the dialog stays open
-  }}
-/>;
-```
-
 ```ts
 import { forwardEscape, keepListEscape } from '@nxgt/material-core/escape-forward';
 
@@ -1259,7 +1232,7 @@ row.addEventListener('click', (event) => {
 
 ### Background presets: `/backgrounds`
 
-The engine under the libraries' background presets, with the grain built so far; the other presets follow.
+The engine under the libraries' background presets: a seeded generator, scattering, motif shapes, a scene format, and a builder for each of the 16 SVG presets.
 A background is a **scene**: a plain tree `{ tag, attrs, children }` of SVG
 elements that each library renders with `createElement` or `h` — never as an
 HTML string. `assertSafeScene` throws for a `style`, an `on*` handler, an
@@ -1298,10 +1271,11 @@ stop();
 (`':r1:'` becomes `'bg-r1'`). `BACKGROUND_PRESETS` is the table of the 20
 preset ids with their family, how each is drawn and whether `seed` changes
 it. `buildBackgroundScene(preset, { idPrefix, seed })` returns the scene of a
-preset, or `null` for a CSS-only one or one with no builder yet (only `grain` has one so far).
-`SHIPPED_BACKGROUND_PRESETS` (`gradient`, `grain`) is what the libraries draw today, and
-`resolveShippedPreset(id)` returns `id` when it ships, else `'gradient'`, with a one-time
-warning outside production. See
+preset, or `null` for a CSS-only one (`gradient`, `mesh`, `dots`, `stripes`).
+`SHIPPED_BACKGROUND_PRESETS` (`gradient`, `grain`) is the common floor every library draws;
+each library lists its own, and `resolveBackgroundPreset(id, available)` returns `id` when the
+list has it, else `'gradient'`, with a one-time warning outside production (`resolveShippedPreset`
+is the same over the floor). `presetLayers(preset)` lists the layers a library renders. See
 [Backgrounds](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/backgrounds.md).
 
 ### One plugin: `nxgtMaterial()` (`/vite`)
@@ -1409,249 +1383,6 @@ You rarely call it yourself: `withNxgtPrint` (`@nxgt/material/next`) turns
 the directories into `outputFileTracingIncludes` globs, and the Nuxt module
 of `@nxgt/material-vue` adds the files to `nitro.externals.traceInclude`.
 
-### An editable grid's pure half: `/data-grid`
-
-The logic behind the editable `DataGrid` that is coming to `@nxgt/material`,
-with nothing rendered yet: where a cell is, which cell a key moves to, what a
-typed text parses to, and the messages to announce. It never reads the DOM, so
-it also runs in a test or on a server. Positions are `{ row, col }`; the header
-row is `-1` and the footer rows follow the body.
-
-```ts
-import {
-	buildGridModel,
-	cellVersion,
-	gridCommandFor,
-	gridPlatform,
-	isGridPos,
-	navigate,
-	numberCodes,
-	validateCell,
-	type GridPos,
-} from '@nxgt/material-core/data-grid';
-
-type Row = { id: string; outOf: number; version?: number };
-
-const model = buildGridModel({
-	columns: [
-		{ id: 'name', label: 'Name', frozen: true },
-		{ id: 'maths', label: 'Maths', editor: 'number' },
-	],
-	rows: [{ id: 'ada' }, { id: 'alan' }],
-});
-
-// A key press is a command, and a command takes the active cell somewhere.
-const key = { key: 'ArrowDown', shiftKey: false, ctrlKey: false, metaKey: false, altKey: false };
-const command = gridCommandFor(key, 'nav', gridPlatform(navigator.platform));
-// { type: 'move', cmd: 'down' }
-
-let active: GridPos = { row: 0, col: 1 };
-if (command?.type === 'move') {
-	const next = navigate(active, command.cmd, {
-		model,
-		pageSize: 10,
-		dir: 'ltr',
-		skipReadOnly: true,
-	});
-	if (isGridPos(next)) active = next; // else 'exit-forward' / 'exit-back': leave the grid
-}
-
-// A number column that also takes codes, in any language, with `,` or `.`.
-const grades = numberCodes<Row>({
-	min: 0,
-	max: (row) => row.outOf,
-	decimals: 2,
-	codes: [{ value: 'ABS', labels: { en: 'abs', fr: 'abs' }, aliases: { fr: ['absent'] } }],
-});
-const row: Row = { id: 'ada', outOf: 20 };
-
-grades.parse('abs', { lang: 'fr', row }); // { value: 'ABS' }
-grades.parse('12,5', { lang: 'fr', row }); // { value: 12.5 }
-grades.parse('25', { lang: 'en', row }); // { error: GridMsg } — "Enter a number from 0 to 20"
-
-// Parse, then the column's check, then a Standard Schema: the first error wins.
-const result = validateCell({
-	text: '12,5',
-	row,
-	parse: (text) => grades.parse(text, { lang: 'fr', row }),
-});
-// { ok: true, value: 12.5 } or { ok: false, error: GridMsg }
-
-// The version the server gave a cell: per cell, else the row's.
-cellVersion(row, 'maths', { getRowVersion: (r) => r.version });
-```
-
-- **Messages are descriptors.** Every error and announcement is a `GridMsg`
-  (`{ key: 'material.data-grid.…', fallback, values? }`): the library
-  translates `key`, and `gridFallbackText(message)` gives the English text.
-- **Versions are passed through unchanged.** `cellVersion` answers
-  `getCellVersion` when it is given, else `getRowVersion`, else `undefined`;
-  `isNewCellVersion` is true for `0` and `undefined`, a cell that does not
-  exist yet on the server.
-- **Numbers are never rounded or clamped.** Too many decimals or a value out
-  of bounds is an error. Spaces are stripped (`"1 234"` is 1234), but a
-  second separator is refused: `"1,234"` is 1.234 and `"1,234.5"` an error.
-  `parse` needs the row; with a bound that is a function of the row and no
-  row, it refuses the number rather than let it through unchecked.
-- **A cleared cell skips the schema.** `null` still runs `validate`, but not
-  the Standard Schema, so a `z.number()` does not refuse a clear; refuse an
-  empty cell in `validate` (or with `numberCodes({ emptyClears: false })`).
-  Without `parse`, the value is the text: a column whose value is not a
-  string must give one.
-- **Tab in an editor always moves on.** `tabBehavior: 'exit'` makes Tab leave
-  the grid from a cell, but a commit's Tab (`commitNext` / `commitPrev`)
-  still walks the cells. `gridCommandFor` returns `{ type: 'swallow' }` for
-  the browser's back and forward (Alt+Arrow, Cmd+[ and Cmd+]): call
-  `preventDefault` and do nothing.
-
-#### Saving changes: the queue
-
-Each edited cell is a change that keeps the value and the version it was read
-at. The queue picks what the next call sends, one call at a time; the answer
-is all or nothing.
-
-```ts
-import {
-	applyAbort,
-	applyAnswer,
-	applyFailure,
-	cellVersion,
-	editCell,
-	expireSaved,
-	gridCellKey,
-	type GridCall,
-	type GridSaveAnswer,
-	IDLE_QUEUE,
-	NO_CHANGES,
-	startCall,
-} from '@nxgt/material-core/data-grid';
-
-type Row = { id: string; maths: number | null; version: number };
-const row: Row = { id: 'ada', maths: 12, version: 3 };
-// The app's save: one call, answered as a whole.
-declare function onSave(entries: GridCall['entries'], signal: AbortSignal): Promise<GridSaveAnswer>;
-
-let changes = NO_CHANGES;
-let queue = IDLE_QUEUE;
-
-// An edit: going back to the value read drops it again.
-changes = editCell(changes, {
-	key: gridCellKey(row.id, 'maths'),
-	base: row.maths,
-	baseVersion: cellVersion(row, 'maths', { getRowVersion: (r) => r.version }),
-	value: 14,
-});
-
-// Cell mode sends everything dirty (200 entries a call at most); row mode the
-// rows left; batch mode only on save(), with no limit, and not while a cell is
-// in error or in conflict.
-const started = startCall(changes, queue, { mode: 'cell' });
-if (started) {
-	({ changes, queue } = started); // its cells are 'saving'
-	const { call } = started;
-	const controller = new AbortController();
-	try {
-		const answer = await onSave(call.entries, controller.signal);
-		// Versions per row (no getCellVersion): the row's other changes move too.
-		({ changes, queue } = applyAnswer(changes, queue, call.id, answer, Date.now(), { versionScope: 'row' }));
-	} catch {
-		({ changes, queue } = controller.signal.aborted
-			? applyAbort(changes, queue, call.id) // no failure counted
-			: applyFailure(changes, queue, call.id)); // paused after 3: retry(queue)
-	}
-}
-changes = expireSaved(changes, Date.now()); // 1.5s later: the "saved" mark goes
-```
-
-- **`versions[i]` is entry `i`'s.** It becomes the cell's new `baseVersion`
-  (every changed cell of the row, in row mode; with `versionScope: 'row'`,
-  the row's other changes still on the old version too). Without one, the
-  version the cell was read at stays, and the next `rebase` adopts the
-  row's: a cell whose value is still its base never conflicts.
-- **A refusal saves nothing.** `{ ok: false, refused }` names entries by index:
-  an `error` flags its cell, a `conflict` opens one (`resolveConflict(changes,
-  key, 'theirs' | 'mine')`), and every other cell goes back to dirty, to be
-  sent again. A cell edited during the call stays dirty either way. A
-  refusal naming no cell sent is counted in `outcome.unmatched`.
-- **A saved value stays until the rows hold it.** It is kept as an overlay
-  (status `'clean'` once the mark expires), as "Keep theirs" is, so the cell
-  never flashes back to stale data. The version a save or a conflict
-  replaced is kept as `staleVersion`: a refetch that still reads at it is
-  older than the grid and changes nothing, and `rebase` drops the overlay
-  once the refetched rows hold the value.
-- **A refetch is a `rebase`.** It compares cell versions when `getCellVersion`
-  is given, else the row's; a pending edit whose version and value moved
-  becomes a conflict, and a conflict outlives any edit until it is resolved.
-
-```ts
-import {
-	aggregate,
-	buildGridModel,
-	conflictValues,
-	EMPTY_HISTORY,
-	type GridCellKey,
-	type GridNumberCodeValue,
-	NO_CHANGES,
-	numberCodes,
-	parseTsv,
-	planPaste,
-	splitCellKey,
-	undo,
-} from '@nxgt/material-core/data-grid';
-
-const changes = NO_CHANGES; // the grid's changes
-const rows = new Map([['ada', { maths: 12 as GridNumberCodeValue }]]);
-const model = buildGridModel({
-	columns: [{ id: 'maths', label: 'Maths', editor: 'number' }],
-	rows: [{ id: 'ada' }],
-});
-const grades = numberCodes({ min: 0, max: 20, decimals: 2 });
-const [lang, locale] = ['fr', 'fr-FR'];
-const valueInRows = (key: GridCellKey) => {
-	const { rowId } = splitCellKey(key);
-	return rows.get(rowId)?.maths;
-};
-
-// Undo is a new edit: send each of `undone.edits` through editCell; `skipped` cells changed since.
-const undone = undo(EMPTY_HISTORY, (key) => changes[key]?.value ?? valueInRows(key)); // null: nothing to undo
-
-// A paste is all or nothing, at the matrix's own size: { ok: true, edits, range } or { ok: false, problems }.
-const plan = planPaste({
-	matrix: parseTsv('14\r\n'),
-	anchor: { row: 0, col: 0 },
-	model,
-	parse: (text) => grades.parse(text, { lang, row: undefined }),
-});
-
-// Totals over numbers only: codes and empty cells are skipped.
-aggregate('mean', [12, 'ABS', null, 14]); // 13; aggregate('count', []) is 0
-
-// The conflict panel's two values, formatted with the column's own format; a cleared one is "Cleared".
-conflictValues({
-	theirs: null,
-	yours: 12.5,
-	format: (value) => grades.format(value as GridNumberCodeValue, { lang, locale }),
-}); // { theirs: Cleared, yours: "12,5" }
-```
-
-### A typed number: `/parse-number`
-
-A number typed with `,` or `.` as its decimal separator, the decimals it was
-typed with, and the clamp and step behind `NumberField` and the data grid's
-number editor.
-
-```ts
-import { clampNumber, decimalsTyped, parseNumberInput, stepNumber } from '@nxgt/material-core/parse-number';
-
-parseNumberInput('12,5'); // 12.5
-parseNumberInput('1 234,5'); // 1234.5: the last of `,` and `.` is the decimal separator
-parseNumberInput('-'); // null: empty or incomplete
-decimalsTyped('12,50'); // 2: a trailing zero is what the user typed
-clampNumber(15, 0, 10); // 10: `min` and `max` are each optional
-stepNumber(1.1, 1, 0.1); // 1.2: no float drift
-stepNumber(null, -1, 1, 0); // 0: empty starts at 0, then is clamped
-```
-
 ## Traps
 
 | Symptom | Fix |

package/dist/backgrounds/build.d.ts

@@ -1,4 +1,12 @@
 import type { BackgroundPreset, SceneNode, SceneOptions } from './types';
+/**
+ * The `data-layer` names of a preset in paint order, the literal `'scene'`
+ * (`SCENE_LAYER`) marking where its SVG scene goes; empty when the preset is
+ * not drawn yet. The libraries render this list, so the markup follows the
+ * table. It reads `PRESET_LAYERS`, which holds no builder, so importing
+ * `presetLayers` alone tree-shakes every preset's drawing code.
+ */
+export declare function presetLayers(preset: BackgroundPreset): readonly string[];
 /**
  * The SVG scene of a preset, or `null` when it has none (the CSS-only
  * presets, and a preset whose builder is not there yet). The same `seed`

package/dist/backgrounds/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/backgrounds/build.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACX,gBAAgB,EAEhB,SAAS,EACT,YAAY,EACZ,MAAM,SAAS,CAAC;AAWjB;;;;;GAKG;AACH,wBAAgB,oBAAoB,CACnC,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,YAAY,GAChB,SAAS,GAAG,IAAI,CAIlB"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/backgrounds/build.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACX,gBAAgB,EAEhB,SAAS,EACT,YAAY,EACZ,MAAM,SAAS,CAAC;AAkBjB;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,MAAM,EAAE,CAExE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CACnC,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,YAAY,GAChB,SAAS,GAAG,IAAI,CAIlB"}

package/dist/backgrounds/index.d.ts

@@ -6,15 +6,16 @@
  * Framework-free; the libraries render a scene with `createElement` / `h`.
  */
 export { observeBackgroundActivity } from './activity';
-export { buildBackgroundScene } from './build';
+export { buildBackgroundScene, presetLayers } from './build';
 export { svgIdPrefix } from './id-prefix';
 export { valueNoise2 } from './noise';
-export { BACKGROUND_PRESETS, resolveShippedPreset, SHIPPED_BACKGROUND_PRESETS, } from './presets';
-export { buildGrain } from './presets/grain';
+export { BACKGROUND_PRESETS, resolveBackgroundPreset, resolveShippedPreset, SHIPPED_BACKGROUND_PRESETS, } from './presets';
+export { buildGrain } from './presets/light/grain';
 export { MOTIF_DEFAULTS, MOTIF_SHAPES, motifShape, type PlaceOptions, place, } from './primitives';
 export { mulberry32, pick, round1 } from './rng';
 export { type ScatterOptions, type ScatterPoint, scatter, } from './scatter';
 export { assertSafeScene, el, SCENE_ATTRIBUTES, SCENE_TAGS, } from './scene';
 export { BACKGROUND_INTENSITIES, BACKGROUND_TONES } from './tones';
 export type { BackgroundIntensity, BackgroundPreset, BackgroundTone, MotifDensity, MotifOptions, MotifShape, MotifSize, OpacitySpread, PresetInfo, SceneBuilder, SceneNode, SceneOptions, SceneTag, ShapeFill, ShippedBackgroundPreset, } from './types';
+export { SCENE_LAYER } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/backgrounds/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backgrounds/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EACN,kBAAkB,EAClB,oBAAoB,EACpB,0BAA0B,GAC1B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EACN,cAAc,EACd,YAAY,EACZ,UAAU,EACV,KAAK,YAAY,EACjB,KAAK,GACL,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AACjD,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,OAAO,GACP,MAAM,WAAW,CAAC;AACnB,OAAO,EACN,eAAe,EACf,EAAE,EACF,gBAAgB,EAChB,UAAU,GACV,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACnE,YAAY,EACX,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,SAAS,EACT,aAAa,EACb,UAAU,EACV,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,uBAAuB,GACvB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backgrounds/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EACN,kBAAkB,EAClB,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,GAC1B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EACN,cAAc,EACd,YAAY,EACZ,UAAU,EACV,KAAK,YAAY,EACjB,KAAK,GACL,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AACjD,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,OAAO,GACP,MAAM,WAAW,CAAC;AACnB,OAAO,EACN,eAAe,EACf,EAAE,EACF,gBAAgB,EAChB,UAAU,GACV,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACnE,YAAY,EACX,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,SAAS,EACT,aAAa,EACb,UAAU,EACV,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,uBAAuB,GACvB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC"}