ngwr 9.1.0 → 10.1.0

package/types/ngwr-toolbar.d.ts

@@ -8,14 +8,14 @@ import * as i0 from '@angular/core';
  * ```html
  * <wr-toolbar>
  *   <div wrToolbarStart>
- *     <button wrButton>Back</button>
+ *     <button wr-btn>Back</button>
  *     <strong>Items</strong>
  *   </div>
  *   <div wrToolbarCenter>
  *     <wr-segmented [(value)]="view" [options]="['grid', 'list']" />
  *   </div>
  *   <div wrToolbarEnd>
- *     <button wrButton color="primary">New</button>
+ *     <button wr-btn color="primary">New</button>
  *   </div>
  * </wr-toolbar>
  * ```

package/types/ngwr-tour.d.ts

@@ -0,0 +1,132 @@
+import * as _angular_core from '@angular/core';
+import * as ngwr_i18n from 'ngwr/i18n';
+
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+/** Where the step popup sits relative to its target. */
+type WrTourPlacement = 'top' | 'bottom' | 'left' | 'right';
+/** One stop on a tour. */
+interface WrTourStep {
+    /**
+     * What to spotlight — a CSS selector resolved when the step opens, or the
+     * element itself. A step whose selector matches nothing is SKIPPED rather than
+     * shown floating: a tour that points at a control the user cannot see is worse
+     * than one that is a step shorter.
+     */
+    readonly target: string | HTMLElement;
+    /** Heading above the copy. */
+    readonly title?: string;
+    /** The step's body text. */
+    readonly content: string;
+    /** Preferred side. The overlay falls back to the opposite side near an edge. @default 'bottom' */
+    readonly placement?: WrTourPlacement;
+}
+
+/**
+ * Guided product tour: a spotlight over one element at a time plus a popup
+ * explaining it.
+ *
+ * Steps are data, not markup — call `start()` with an array and the service owns
+ * the overlay, the cut-out, focus and the keyboard. A step whose target is not
+ * on the page is skipped rather than shown floating, so a tour survives a
+ * feature being hidden behind a flag or a permission.
+ *
+ * @example
+ * ```ts
+ * private readonly tour = inject(WrTour);
+ *
+ * showMeAround(): void {
+ *   this.tour.start([
+ *     { target: '[data-tour="search"]', title: 'Search', content: 'Find anything by name.' },
+ *     { target: '[data-tour="filters"]', content: 'Narrow the list down.', placement: 'right' },
+ *   ]);
+ * }
+ * ```
+ *
+ * @see https://ngwr.dev/reference/services/tour
+ */
+declare class WrTour {
+    private readonly overlay;
+    private readonly scrollStrategies;
+    private readonly injector;
+    private readonly focusTrapFactory;
+    private readonly document;
+    private readonly isBrowser;
+    private readonly steps;
+    private readonly cursor;
+    private overlayRef;
+    private spotlight;
+    private detachKeydown;
+    private detachReposition;
+    private restoreFocus;
+    /** Whether a tour is running. */
+    readonly active: _angular_core.Signal<boolean>;
+    /** Zero-based index of the current step, `-1` when idle. */
+    readonly index: _angular_core.Signal<number>;
+    /** How many steps this tour has. */
+    readonly total: _angular_core.Signal<number>;
+    /** The step being shown, or `null` when idle. */
+    readonly step: _angular_core.Signal<WrTourStep | null>;
+    /**
+     * Begin a tour. Restarts if one is already running. A no-op under SSR — a
+     * tour is a client-side affordance and there is nothing to spotlight on the
+     * server.
+     */
+    start(steps: readonly WrTourStep[]): void;
+    /** Advance; finishes the tour past the last step. */
+    next(): void;
+    /** Go back; stays put on the first step. */
+    prev(): void;
+    /** End the tour and return focus where it was. */
+    stop(): void;
+    /**
+     * Move to `index`, skipping steps whose target is not in the DOM. `direction`
+     * says which way to keep skipping, so a missing step never traps the tour
+     * between two dead ends.
+     */
+    private goTo;
+    private resolve;
+    private openStep;
+    private placeSpotlight;
+    private teardownStep;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrTour, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<WrTour>;
+}
+
+/** What the popup needs from the running tour, without importing the service (cycle). */
+interface WrTourController {
+    readonly index: () => number;
+    readonly total: () => number;
+    readonly step: () => WrTourStep | null;
+    next(): void;
+    prev(): void;
+    stop(): void;
+}
+/**
+ * The card a tour shows next to the spotlit element. Rendered by `WrTour` into
+ * a CDK overlay — not something you place yourself.
+ *
+ * @see https://ngwr.dev/reference/services/tour
+ */
+declare class WrTourPopup {
+    protected readonly tour: WrTourController;
+    protected readonly nextLabel: string;
+    protected readonly backLabel: string;
+    protected readonly doneLabel: string;
+    protected readonly skipLabel: string;
+    /** `Step {{current}} of {{total}}` — also the dialog's accessible name. */
+    protected readonly progress: (params?: ngwr_i18n.WrI18nParams) => string;
+    protected readonly isLast: _angular_core.Signal<boolean>;
+    protected readonly isFirst: _angular_core.Signal<boolean>;
+    protected readonly progressText: _angular_core.Signal<string>;
+    protected readonly ariaLabel: _angular_core.Signal<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrTourPopup, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrTourPopup, "wr-tour-popup", never, {}, {}, never, never, true, never>;
+}
+
+export { WrTour, WrTourPopup };
+export type { WrTourPlacement, WrTourStep };

package/types/ngwr-transfer.d.ts

@@ -0,0 +1,118 @@
+import * as ngwr_i18n from 'ngwr/i18n';
+import * as _angular_core from '@angular/core';
+import { FormValueControl } from '@angular/forms/signals';
+
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+/** One row in either pane of a `<wr-transfer>`. */
+interface WrTransferItem<TValue = unknown> {
+    /** Identity — what `[(value)]` carries, compared with SameValueZero. */
+    readonly value: TValue;
+    /** Text shown in the pane and matched by the search box. */
+    readonly label: string;
+    /** Greyed out and never moved by the bulk buttons. */
+    readonly disabled?: boolean;
+}
+
+/** A pane's rows plus the header state derived from them. */
+interface PaneState {
+    readonly rows: readonly WrTransferItem[];
+    readonly checkedCount: number;
+    readonly allChecked: boolean;
+    readonly someChecked: boolean;
+}
+/**
+ * Dual-listbox picker: two panes and the buttons that move rows between them.
+ *
+ * The full item set is `[items]` and the RIGHT pane is the value — `[(value)]`
+ * holds the chosen `WrTransferItem['value']`s, everything else stays left. The
+ * checked state inside each pane is transient staging, deliberately not part of
+ * the value: what a form cares about is which rows ended up on the right.
+ *
+ * A signal-forms native control (`FormValueControl<readonly unknown[]>`), so
+ * `[formField]` binds straight to `value`; `[(ngModel)]` and reactive forms keep
+ * working through Angular's bridge, and `[(value)]` is the standalone shape.
+ *
+ * @example
+ * ```html
+ * <!-- Standalone -->
+ * <wr-transfer [items]="permissions" [(value)]="granted" />
+ *
+ * <!-- Searchable, with pane titles -->
+ * <wr-transfer
+ *   searchable
+ *   sourceTitle="Available"
+ *   targetTitle="Granted"
+ *   [items]="permissions"
+ *   [formField]="form.granted"
+ * />
+ * ```
+ *
+ * @see https://ngwr.dev/reference/components/transfer
+ */
+declare class WrTransfer implements FormValueControl<readonly unknown[]> {
+    /** Every row, in either pane. Membership of the right pane is `value`. */
+    readonly items: _angular_core.InputSignal<readonly WrTransferItem<unknown>[]>;
+    /**
+     * Values currently in the RIGHT pane. Two-way bindable; bound automatically
+     * by `[formField]` / `[(ngModel)]`.
+     */
+    readonly value: _angular_core.ModelSignal<readonly unknown[]>;
+    /** Emitted on blur / commit so a bound field marks itself touched. */
+    readonly touch: _angular_core.OutputEmitterRef<void>;
+    /** Disable the whole control. @default false */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, any>;
+    /** Show a filter box above each pane. @default false */
+    readonly searchable: _angular_core.InputSignalWithTransform<boolean, any>;
+    /** Heading above the left pane. Falls back to `transfer.source`. */
+    readonly sourceTitle: _angular_core.InputSignal<string | null>;
+    /** Heading above the right pane. Falls back to `transfer.target`. */
+    readonly targetTitle: _angular_core.InputSignal<string | null>;
+    /** Placeholder in both filter boxes. Falls back to `transfer.search`. */
+    readonly searchPlaceholder: _angular_core.InputSignal<string | null>;
+    /** Shown in a pane with no rows. Falls back to `transfer.empty`. */
+    readonly emptyText: _angular_core.InputSignal<string | null>;
+    /** Accessible name of the move-right button. Falls back to `transfer.toTarget`. */
+    readonly toTargetLabel: _angular_core.InputSignal<string | null>;
+    /** Accessible name of the move-left button. Falls back to `transfer.toSource`. */
+    readonly toSourceLabel: _angular_core.InputSignal<string | null>;
+    protected readonly resolvedSourceTitle: _angular_core.Signal<string>;
+    protected readonly resolvedTargetTitle: _angular_core.Signal<string>;
+    protected readonly resolvedSearch: _angular_core.Signal<string>;
+    protected readonly resolvedEmpty: _angular_core.Signal<string>;
+    protected readonly resolvedToTarget: _angular_core.Signal<string>;
+    protected readonly resolvedToSource: _angular_core.Signal<string>;
+    /** `{{checked}} / {{total}}` under each heading. @internal */
+    protected readonly countLabel: (params?: ngwr_i18n.WrI18nParams) => string;
+    /** Pane order — the template iterates it so both panes share one block. */
+    protected readonly panes: readonly ["source", "target"];
+    private readonly sourceQuery;
+    private readonly targetQuery;
+    /** Staged rows, per pane. Cleared as soon as a move commits them. */
+    private readonly sourceChecked;
+    private readonly targetChecked;
+    private readonly valueSet;
+    protected readonly source: _angular_core.Signal<PaneState>;
+    protected readonly target: _angular_core.Signal<PaneState>;
+    protected readonly canMoveRight: _angular_core.Signal<boolean>;
+    protected readonly canMoveLeft: _angular_core.Signal<boolean>;
+    protected readonly classes: _angular_core.Signal<string>;
+    protected isChecked(pane: 'source' | 'target', item: WrTransferItem): boolean;
+    protected toggle(pane: 'source' | 'target', item: WrTransferItem, checked: boolean): void;
+    /** Header checkbox — stages or clears every enabled row the filter shows. */
+    protected toggleAll(pane: 'source' | 'target', checked: boolean): void;
+    protected onSearch(pane: 'source' | 'target', event: Event): void;
+    protected moveRight(): void;
+    protected moveLeft(): void;
+    /** Filter, then derive the header state from what survived. */
+    private pane;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrTransfer, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrTransfer, "wr-transfer", never, { "items": { "alias": "items"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "searchable": { "alias": "searchable"; "required": false; "isSignal": true; }; "sourceTitle": { "alias": "sourceTitle"; "required": false; "isSignal": true; }; "targetTitle": { "alias": "targetTitle"; "required": false; "isSignal": true; }; "searchPlaceholder": { "alias": "searchPlaceholder"; "required": false; "isSignal": true; }; "emptyText": { "alias": "emptyText"; "required": false; "isSignal": true; }; "toTargetLabel": { "alias": "toTargetLabel"; "required": false; "isSignal": true; }; "toSourceLabel": { "alias": "toSourceLabel"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "touch": "touch"; }, never, never, true, never>;
+}
+
+export { WrTransfer };
+export type { WrTransferItem };

package/types/ngwr-tree.d.ts

@@ -93,6 +93,14 @@ declare class WrTree<TId = string> implements FormValueControl<unknown> {
     readonly openOn: _angular_core.InputSignal<"inline" | "overlay">;
     /** Placeholder shown on the trigger when no node is selected. */
     readonly placeholder: _angular_core.InputSignal<string>;
+    /**
+     * Accessible name of the overlay trigger. Falls back to the placeholder, then
+     * to `select.label` — a `role="combobox"` with nothing selected and no
+     * placeholder otherwise has no name at all.
+     */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    private readonly labelText;
+    protected readonly resolvedAriaLabel: _angular_core.Signal<string>;
     /** Show a clear-all (×) button on the trigger when at least one node is selected. @default true */
     readonly clearable: _angular_core.InputSignalWithTransform<boolean, any>;
     /**
@@ -138,13 +146,14 @@ declare class WrTree<TId = string> implements FormValueControl<unknown> {
     readonly touch: _angular_core.OutputEmitterRef<void>;
     private readonly host;
     private readonly overlay;
+    private readonly outsideClick;
     private readonly vcr;
     private readonly scrollStrategies;
     private readonly destroyRef;
     private readonly platformId;
     /** Currently focused row's index in the flattened visible list. */
     protected readonly focusedIndex: _angular_core.WritableSignal<number>;
-    /** Resolved ARIA labels — pick up live locale changes via re-render. */
+    /** Resolved ARIA labels — resolved once at construction, so a runtime locale switch needs a re-create. */
     protected readonly clearLabel: string;
     protected readonly expandLabel: string;
     protected readonly collapseLabel: string;
@@ -224,7 +233,7 @@ declare class WrTree<TId = string> implements FormValueControl<unknown> {
     private openOverlay;
     private closeOverlay;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrTree<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrTree<any>, "wr-tree", never, { "nodes": { "alias": "nodes"; "required": false; "isSignal": true; }; "selected": { "alias": "selected"; "required": false; "isSignal": true; }; "expanded": { "alias": "expanded"; "required": false; "isSignal": true; }; "selectionMode": { "alias": "selectionMode"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "openOn": { "alias": "openOn"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "clearable": { "alias": "clearable"; "required": false; "isSignal": true; }; "maxTagCount": { "alias": "maxTagCount"; "required": false; "isSignal": true; }; "defaultExpandAll": { "alias": "defaultExpandAll"; "required": false; "isSignal": true; }; "virtualScroll": { "alias": "virtualScroll"; "required": false; "isSignal": true; }; "rowHeight": { "alias": "rowHeight"; "required": false; "isSignal": true; }; "viewportHeight": { "alias": "viewportHeight"; "required": false; "isSignal": true; }; "overscan": { "alias": "overscan"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "selected": "selectedChange"; "expanded": "expandedChange"; "value": "valueChange"; "touch": "touch"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrTree<any>, "wr-tree", never, { "nodes": { "alias": "nodes"; "required": false; "isSignal": true; }; "selected": { "alias": "selected"; "required": false; "isSignal": true; }; "expanded": { "alias": "expanded"; "required": false; "isSignal": true; }; "selectionMode": { "alias": "selectionMode"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "openOn": { "alias": "openOn"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "clearable": { "alias": "clearable"; "required": false; "isSignal": true; }; "maxTagCount": { "alias": "maxTagCount"; "required": false; "isSignal": true; }; "defaultExpandAll": { "alias": "defaultExpandAll"; "required": false; "isSignal": true; }; "virtualScroll": { "alias": "virtualScroll"; "required": false; "isSignal": true; }; "rowHeight": { "alias": "rowHeight"; "required": false; "isSignal": true; }; "viewportHeight": { "alias": "viewportHeight"; "required": false; "isSignal": true; }; "overscan": { "alias": "overscan"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "selected": "selectedChange"; "expanded": "expandedChange"; "value": "valueChange"; "touch": "touch"; }, never, never, true, never>;
 }
 
 export { WrTree };

package/types/ngwr-validators.d.ts

@@ -8,8 +8,11 @@ import { AbstractControl, ValidationErrors, ValidatorFn } from '@angular/forms';
  */
 
 /**
- * Bundled `ValidatorFn`s — pure functions, no DOM, no DI. Mirrors the
- * API shape of Angular's built-in `Validators` so it composes cleanly:
+ * Bundled `ValidatorFn`s — pure functions, no DOM, no DI. (`matchFields` keeps
+ * one bit of per-instance state, a latch so its dev-mode misconfiguration
+ * warning fires once rather than on every validation run; it is never read as
+ * part of the result.) Mirrors the API shape of Angular's built-in
+ * `Validators` so it composes cleanly:
  *
  * ```ts
  * import { Validators } from '@angular/forms';
@@ -59,8 +62,65 @@ declare const WrValidators: {
      * Value must equal a sibling control's value (e.g. confirm-password).
      * The target lookup uses `control.parent.get(name)`, so it works
      * inside `FormGroup` and nested groups.
+     *
+     * **It cannot report a mismatch until something revalidates the control.**
+     * Angular runs a control's validators inside the control's own constructor,
+     * before the control has a parent — so the lookup finds nothing and this
+     * returns `null`, and attaching the control to a group does not re-run it.
+     *
+     * `formControlName` revalidates when it binds, so a group rendered through
+     * the reactive-forms directives corrects itself on its first change
+     * detection. The window is open for everything that reads validity BEFORE
+     * that: a route guard or resolver checking `form.valid`, a form built and
+     * submitted from a service, a unit test. Such a group reports itself valid
+     * with two values that plainly disagree.
+     *
+     * Put {@link WrValidators.matchFields} on the group to close it, and keep
+     * this one on the child for the per-field message. They do not conflict —
+     * different error keys, different hosts.
+     *
+     * @see WrValidators.matchFields
      */
     match: (targetName: string) => ValidatorFn;
+    /**
+     * Every named control must hold the same value — the group-level counterpart
+     * to {@link WrValidators.match}. Attach it to the group that OWNS the fields,
+     * not to one of its children.
+     *
+     * Unlike `match` this has no ordering hole: Angular attaches the children and
+     * aggregates their values BEFORE it runs the group's own validators, so a
+     * group built from a record whose fields already disagree is invalid the
+     * moment it exists — no revalidation step, and nothing that depends on the
+     * form having been rendered.
+     *
+     * Names are `AbstractControl.get()` paths, so `'billing.zip'` reaches into a
+     * nested group. `null`, `undefined` and `''` all count as the same empty
+     * value; everything else is compared with `===`, so two equal `Date`s are NOT
+     * equal — compare a derived primitive instead. **Disabled controls are
+     * skipped**, which makes the rule compare exactly what `group.value`
+     * contains, and the error names only the controls it actually compared.
+     *
+     * A name that resolves to nothing, or to a group or an array rather than a
+     * leaf control, turns the whole check off and warns once per validator
+     * instance in dev — never a partial comparison of the names that did
+     * resolve, and never an error the user has no way to satisfy.
+     *
+     * The error lands on the GROUP, and `<wr-form-field>` only reads the one
+     * control projected into it — so pair this with `match` for a per-field
+     * message, or render it yourself from `form.hasError('matchFields')`.
+     *
+     * @example
+     * ```ts
+     * new FormGroup(
+     *   {
+     *     password: new FormControl(''),
+     *     confirm: new FormControl('', [WrValidators.match('password')]),
+     *   },
+     *   { validators: [WrValidators.matchFields('password', 'confirm')] },
+     * );
+     * ```
+     */
+    matchFields: (first: string, second: string, ...rest: readonly string[]) => ValidatorFn;
     /** Value must be one of the allowed entries (strict equality). */
     oneOf: <T>(allowed: readonly T[]) => ValidatorFn;
     /** Value (Date | parseable) must be ≥ `min`. */

package/types/ngwr-version.d.ts

@@ -14,9 +14,9 @@ import { InjectionToken } from '@angular/core';
  * import or `require`, neither of which tree-shakes well in Angular builds.
  *
  * Distinct from `Version` exported by `@angular/core`, which reports the
- * loaded Angular runtime version (e.g. `'21.2.13'`), not ngwr's.
+ * loaded Angular runtime version (e.g. `'22.0.0'`), not ngwr's.
  */
-declare const NGWR_VERSION = "9.1.0";
+declare const NGWR_VERSION = "10.1.0";
 
 /**
  * @license

package/types/ngwr-waves.d.ts

@@ -53,6 +53,16 @@ declare class WrWaves {
     private bounding;
     private readonly mouse;
     private rafId;
+    /**
+     * Flips once the canvas has drawn, which retires the CSS stand-in grid.
+     *
+     * A canvas cannot be prerendered, so on an SSR'd or prerendered page this
+     * element is simply blank until the bundle has loaded and hydration has run —
+     * measured at ~2.8s on ngwr.dev's own home page. The stylesheet paints a static
+     * grid of the same colour and pitch in the meantime, straight from the
+     * prerendered HTML, and this hands over to the real thing.
+     */
+    protected readonly painted: _angular_core.WritableSignal<boolean>;
     constructor();
     private boot;
     private setSize;

package/typewriter/styles/_index.scss

@@ -1,3 +1,8 @@
+// Pull the whole theme so a standalone `@use 'ngwr/<name>'` brings in every
+// design token this stylesheet references. Sass deduplicates `@use` per
+// compilation, so the umbrella sheet still emits the theme only once.
+@use '../../theme/styles' as theme;
+
 .wr-typewriter {
   --wr-typewriter-cursor-blink: 0.5s;
 

package/typography/styles/_index.scss

@@ -174,13 +174,13 @@
     color: var(--wr-color-primary);
   }
   &--tone-success {
-    color: var(--wr-color-success);
+    color: var(--wr-color-success-ink);
   }
   &--tone-warning {
-    color: var(--wr-color-warning);
+    color: var(--wr-color-warning-ink);
   }
   &--tone-danger {
-    color: var(--wr-color-danger);
+    color: var(--wr-color-danger-ink);
   }
 
   // Modifiers

package/virtual-scroll/styles/_index.scss

@@ -1,3 +1,8 @@
+// Pull the whole theme so a standalone `@use 'ngwr/<name>'` brings in every
+// design token this stylesheet references. Sass deduplicates `@use` per
+// compilation, so the umbrella sheet still emits the theme only once.
+@use '../../theme/styles' as theme;
+
 // Fixed-size virtual scroll wrapper. Most of the layout work is done by
 // CDK's `<cdk-virtual-scroll-viewport>`; this stylesheet just makes the
 // host a block-level container and tames default overflow behaviour.
@@ -11,7 +16,7 @@
     width: 100%;
     height: 100%;
     // CDK already sets `overflow: auto`; just add a discreet scrollbar
-    // skin via the platform defaults — no custom thumb so we match the
+    // skin via the platform defaults — a discreet custom thumb that still matches the
     // host application's chrome.
     scrollbar-width: thin;
 

package/waves/styles/_index.scss

@@ -1,9 +1,17 @@
+// Pull the whole theme so a standalone `@use 'ngwr/<name>'` brings in every
+// design token this stylesheet references. Sass deduplicates `@use` per
+// compilation, so the umbrella sheet still emits the theme only once.
+@use '../../theme/styles' as theme;
+
 // Wave-field background (reactbits port). The host fills its nearest
 // positioned ancestor; the line colour is theme-aware via
 // `--wr-waves-line-color` unless `[lineColor]` overrides it.
 
 .wr-waves {
   --wr-waves-line-color: rgba(var(--wr-color-on-surface-rgb), 0.12);
+  // Mirrors the `xGap` input; the component publishes it so the stand-in below
+  // lands on the same pitch as the real grid.
+  --wr-waves-x-gap: 10px;
 
   position: absolute;
   inset: 0;
@@ -12,6 +20,24 @@
   padding: 0;
   overflow: hidden;
 
+  // Stand-in grid, shown until the canvas has painted.
+  //
+  // A canvas cannot be prerendered, so on an SSR'd or prerendered page this
+  // element is blank until the JS bundle has loaded and hydrated — measured at
+  // ~2.8s on ngwr.dev's own home page, where it reads as the background hanging
+  // and then popping in. These are straight lines rather than the drifting
+  // curves, at the same colour and pitch, so the handover reads as the grid
+  // coming alive rather than as content appearing.
+  background-image: repeating-linear-gradient(
+    to right,
+    var(--wr-waves-line-color) 0 1px,
+    transparent 1px var(--wr-waves-x-gap)
+  );
+
+  &--painted {
+    background-image: none;
+  }
+
   &__canvas {
     display: block;
     width: 100%;