ngwr 15.0.1 → 15.2.0

package/types/ngwr-bits-iridescence.d.ts

@@ -0,0 +1,244 @@
+import * as i0 from "@angular/core";
+/**
+ * Iridescence background — folded silk under a raking light, its hue turning
+ * with the slope of each fold from pale rose through lilac to sky, on a WebGL2
+ * canvas. The folds drift and swell on their own, and the pointer stirs them,
+ * bending the drape rather than sliding the picture. Fills its nearest positioned
+ * ancestor: put it first in a `position: relative` box and give the content after
+ * it a position of its own.
+ *
+ * The pointer is followed on the host's PARENT, with passive listeners, so the
+ * silk answers a pointer that is over the content in front of it rather than over
+ * the canvas — the host itself takes no pointer events and never steals a click.
+ * Placed directly in a shadow root, where it has no parent element, it follows
+ * the pointer on the shadow host; with neither it listens nowhere.
+ *
+ * Decorative only: the canvas is `aria-hidden`, the host has no role and nothing
+ * in it takes focus or a click.
+ *
+ * The frame loop runs only while the host is on screen with a box to draw on and
+ * something can move: not at `speed` 0 with no pointer to follow, where one still
+ * frame is drawn. At
+ * `speed` 0 with the pointer followed, the loop runs and draws only while the
+ * pointer is stirring something. Off screen it stops asking for frames and resumes
+ * where it left off.
+ *
+ * Under `prefers-reduced-motion`, read live, one still frame is drawn and nothing
+ * follows — no loop, no pointer listeners, the pointer back at rest. It is held at
+ * the phases the folds had reached, so switching the preference on does not jump
+ * them, and it is drawn again when the colour, the box or the page's colour scheme
+ * changes.
+ *
+ * `[color]` is multiplied over the picture, so white leaves it as it is, and it
+ * defaults to the `--wr-iridescence-color` hook: white on a light page, a deep
+ * slate blue on a dark one. Any CSS colour works, a `var()` token or a
+ * `light-dark()` pair included, resolved through the cascade before it reaches the
+ * shader, which reads neither. Pass an opaque colour: the canvas drops alpha and
+ * the stand-in keeps it.
+ *
+ * Measured over 240 phase combinations, with the pointer at rest and at the box's
+ * four corners at `amplitude` 1, `--wr-color-on-surface` holds 4.5:1 on the dark
+ * default (5.01:1 at the 99th-percentile pixel, 4.89:1 in the worst frame) and not
+ * on the light one (3.93:1 at the 1st-percentile pixel, 2.8:1 in the worst frame),
+ * so text there needs a scrim or a card.
+ *
+ * The host's own background is a stand-in: soft diagonal bands in the same palette,
+ * which an opaque colour tints the same way. The stand-in shows before hydration on a
+ * prerendered page, on a machine with no WebGL2 and after a lost context, so the box
+ * is never empty and text placed on it keeps its ground. The canvas fades in over it,
+ * because the stand-in is an approximation and not the same picture, so
+ * `.wr-iridescence--painted` hands over rather than swaps.
+ *
+ * Under forced colours the canvas is hidden and its loop stops with it, leaving the
+ * box on the palette's own ground, which is what forced text and marks are chosen
+ * against.
+ *
+ * With no WebGL2 context, or a shader the driver refuses, nothing is thrown and
+ * the stand-in stays. A context the browser takes away is rebuilt if it offers one
+ * back. A destroyed host hands its GPU resources back at once. Browsers keep a small
+ * number of live contexts and kill the oldest: Chromium frees the slot at that point,
+ * while WebKit frees it only when the context is collected and offers an evicted one
+ * no restore, so there a host that is not drawing can stay on the stand-in for good.
+ *
+ * @example
+ * ```html
+ * <section style="position: relative; min-height: 24rem; padding: 2rem; overflow: hidden">
+ *   <wr-iridescence />
+ *   <wr-card style="max-width: 26rem">
+ *     <h1>Hero copy on a card above the silk</h1>
+ *   </wr-card>
+ * </section>
+ * ```
+ *
+ * @see https://ngwr.dev/bits/iridescence
+ */
+export declare class WrIridescence {
+  /**
+   * Tint multiplied over the picture, any CSS colour — a `var()` token or a
+   * `light-dark()` pair included. Pass an opaque colour: the canvas drops alpha and
+   * the stand-in keeps it. When unset, empty or blank, `--wr-iridescence-color`
+   * decides.
+   */
+  readonly color: import("@angular/core").InputSignal<string | null>;
+  /**
+   * Speed of the folds; `0` holds them and a negative value reverses them.
+   * Changing it never jumps the picture. @default 1
+   */
+  readonly speed: import("@angular/core").InputSignalWithTransform<number, unknown>;
+  /**
+   * How hard the pointer stirs the folds; `0` leaves the pointer out and a
+   * negative value stirs them the other way. @default 1
+   */
+  readonly amplitude: import("@angular/core").InputSignalWithTransform<number, unknown>;
+  /** Whether the pointer stirs the folds at all. @default true */
+  readonly followPointer: import("@angular/core").InputSignalWithTransform<boolean, any>;
+  /**
+   * A colour the author chose, published so the stand-in takes it too; `null` while
+   * the input is unset. On a variable of its own rather than on the hook, which an
+   * author sets from outside: a `null` binding wipes a value of its own name from the
+   * host's `style` attribute.
+   */
+  protected readonly standInColor: import("@angular/core").Signal<string | null>;
+  /** The colour the canvas resolves: an input that is unset, empty or blank leaves the hook in charge. */
+  private readonly expression;
+  /** Whether the pointer is listened for: never under `prefers-reduced-motion`, read live. */
+  private readonly listening;
+  /**
+   * Whether anything can change between two frames. While it is `false` there is
+   * no loop, only a still frame.
+   */
+  private readonly moving;
+  /**
+   * Flips once the canvas has drawn, which fades it in over the stand-in. Set
+   * inside the draw rather than at the end of the boot, so a canvas with nothing
+   * on it is never shown, and back to `false` with a lost context.
+   */
+  protected readonly painted: import("@angular/core").WritableSignal<boolean>;
+  private readonly canvasRef;
+  private readonly host;
+  private readonly zone;
+  private readonly destroyRef;
+  private readonly platform;
+  private readonly isBrowser;
+  private gl;
+  private gpu;
+  /** The size the canvas is backed at, in bitmap pixels. */
+  private bitmap;
+  private rafId;
+  /** The three phases, each in `[0, 2π)`. Kept across a parked loop, so the folds resume in place. */
+  private readonly phase;
+  /**
+   * `uPointer` as drawn (`x`, `y`), and where it is heading before `amplitude`
+   * (`aimX`, `aimY`). `amplitude` is applied per frame rather than kept in the aim,
+   * so changing it eases over like any other move instead of jumping.
+   */
+  private readonly pointer;
+  /** The last pointer position in viewport coordinates, while a frame still owes it a look at the host's rect. */
+  private lastMove;
+  /** The last colour string the cascade resolved to, and its channels: the parse is skipped while it holds. */
+  private resolved;
+  private channels;
+  /**
+   * Whether the picture changed since the loop last drew it — the colour, the
+   * scheme, a restart. The loop skips the frames that would only repeat the last
+   * one, and this is what makes it draw again.
+   */
+  private dirty;
+  /** Flips once a program is built, and back when the context goes — everything that draws waits for it. */
+  private readonly booted;
+  /** Whether the host is in the viewport; stays `true` without an observer. */
+  private readonly onScreen;
+  /**
+   * Whether the bitmap has an area. The intersection observer calls a zero-area
+   * canvas intersecting and sends no entry when it gains a size, so this reads the
+   * bitmap instead.
+   */
+  private readonly hasBox;
+  constructor();
+  private boot;
+  /**
+   * Compile, link and upload what one context needs, and make it current. Returns
+   * `null` when it cannot: on a lost context, where every call answers no and
+   * nothing is wrong with the shader, it says nothing.
+   */
+  private build;
+  private compile;
+  /**
+   * Give the GPU resources back at once rather than to the garbage collector:
+   * browsers keep a small number of live contexts and kill the oldest, so a
+   * navigating single-page app would lose the context of a page still on screen.
+   * Chromium frees the slot here too. WebKit holds it until the context is collected,
+   * and no API frees it sooner, so a still or parked host can still be evicted there.
+   */
+  private release;
+  /**
+   * Back the canvas for a `width` × `height` box, in CSS pixels. Returns whether
+   * anything changed: writing `canvas.width` clears the bitmap even to the value it
+   * already has, so an unchanged size is left alone. Rounded down, because rounding
+   * to nearest could carry a box back over the budget it was just scaled under.
+   */
+  private fit;
+  /** Start the folds, and the pointer listeners when asked; returns what stops both. */
+  private animate;
+  /**
+   * Step the phases by `step` ms, and return whether they moved. Stepped rather
+   * than computed from a clock: a clock times `speed` is a different angle the
+   * moment `speed` changes, so moving the input would jump the picture, and here
+   * it only changes how far the next step goes.
+   */
+  private turn;
+  /**
+   * Follow the pointer. On the parent, not the host: content in front of the canvas
+   * receives the pointer, and its events bubble to the parent, never to a sibling.
+   * Placed directly in a shadow root it has none, and the shadow host is where those
+   * composed events land. Never the host itself, which takes no pointer events and
+   * so could never hear one.
+   */
+  private listenToPointer;
+  private aimAtRest;
+  /**
+   * Bring the pointer towards its target by `step` ms, and return whether it moved.
+   *
+   * The rect is read here, at most once a frame, rather than on every event, and it
+   * is the box as drawn, after any transform on an ancestor, so a pointer lands where
+   * it is seen. The offset is relative to the box, so a transform needs nothing more.
+   */
+  private easePointer;
+  /** Bring the canvas up to date after the picture changed: a still frame now, or the loop's next one. */
+  private repaint;
+  /**
+   * One frame at the current phases and pointer. Leaves `dirty` set when it has
+   * nothing to draw on, a lost context or an empty box, so the next chance draws.
+   */
+  private draw;
+  /**
+   * The tint as shader channels. Resolved through the cascade on every draw, since
+   * a uniform reads neither a `var()` nor a `light-dark()` and a hook changed by a
+   * rule on the host should reach the next frame, and parsed only when that string
+   * changes.
+   */
+  private tint;
+  static ɵfac: i0.ɵɵFactoryDeclaration<WrIridescence, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<WrIridescence, "wr-iridescence", never, {
+    "color": {
+      "alias": "color";
+      "required": false;
+      "isSignal": true;
+    };
+    "speed": {
+      "alias": "speed";
+      "required": false;
+      "isSignal": true;
+    };
+    "amplitude": {
+      "alias": "amplitude";
+      "required": false;
+      "isSignal": true;
+    };
+    "followPointer": {
+      "alias": "followPointer";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}

package/types/ngwr-bits-ripple-grid-testing.d.ts

@@ -0,0 +1,96 @@
+import { BaseHarnessFilters, ComponentHarness, HarnessPredicate } from "@angular/cdk/testing";
+/** Narrows which `<wr-ripple-grid>` a harness query matches. */
+interface WrRippleGridHarnessFilters extends BaseHarnessFilters {
+  /**
+   * Match only grids whose canvas has drawn (`true`) or only grids still showing the
+   * stand-in lines (`false`). A ripple grid has no name of its own, so this is the one
+   * state that tells two of them apart — see `WrRippleGridHarness.isPainted`, which
+   * explains why the answer is always `false` in a unit test.
+   */
+  readonly painted?: boolean;
+}
+/**
+ * Test harness for `<wr-ripple-grid>` — grid lines the pointer sends ripples through.
+ *
+ * **The lines and the ripples are unreadable and always will be.** They are strokes on
+ * a 2D canvas, laid out from the host's measured box and bent by rings that exist only
+ * while frames run; a unit test has no box and no drawing context, so there is nothing
+ * to count and nothing to compare. What the component publishes to the DOM is small
+ * and deliberate: the handover flag {@link isPainted}, the cell {@link getCellSizePx}
+ * and line width {@link getLineWidthPx} the CSS stand-in grid draws at before the
+ * canvas takes over, and the surface itself.
+ *
+ * Both numbers are read from the host's inline declaration, never computed: the
+ * stylesheet declares `--wr-ripple-grid-cell-size` and `--wr-ripple-grid-line-width`
+ * too, as the stand-in's own defaults, so a computed read would answer `40` and `1` on
+ * a component that had stopped publishing anything — the break the methods exist to
+ * catch.
+ *
+ * There is no `getLineCount()`, `getRipples()` or `getCanvasSize()`: the grid is laid
+ * out from the host's layout box, which is 0×0 here, and the rings live in a frame
+ * loop jsdom never runs. No `getLineColor()` or `getRippleColor()` — they are canvas
+ * strokes resolved from themed custom properties that only a stylesheet supplies. No
+ * `press()` or `moveTo()`: the pointer listeners go on only once a context exists, and
+ * what they move is canvas pixels. No `isIdle()`: the idle ring is a timer and a frame,
+ * and neither leaves a trace in the DOM. And no `isReducedMotion()`: the still grid is
+ * drawn through the same code and sets the same flag, so the DOM is identical either
+ * way and any answer would be a guess.
+ *
+ * @example
+ * ```ts
+ * const grid = await loader.getHarness(WrRippleGridHarness);
+ *
+ * expect(await grid.hasCanvas()).toBe(true);
+ * expect(await grid.isDecorative()).toBe(true);
+ * expect(await grid.getCellSizePx()).toBe(40);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+export declare class WrRippleGridHarness extends ComponentHarness {
+  static hostSelector: string;
+  /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+  static with(options?: WrRippleGridHarnessFilters): HarnessPredicate<WrRippleGridHarness>;
+  private readonly canvas;
+  /**
+   * Whether the canvas has drawn a frame and retired the CSS stand-in grid.
+   *
+   * **In a unit test this is always `false`, and asserting exactly that is the point.**
+   * jsdom hands back no 2D context, so the component must leave the stand-in up rather
+   * than declare itself painted over a blank box — the flag is set inside the draw for
+   * that reason, not at the end of the boot. A spec that waits for this to turn `true`
+   * waits forever.
+   */
+  isPainted(): Promise<boolean>;
+  /**
+   * The distance between grid lines, in pixels, as the component publishes it —
+   * `[cellSize]`, floored at the 12px the canvas lays the grid out at.
+   *
+   * The canvas half of `[cellSize]` is invisible here, but the stand-in half is not,
+   * and a stand-in drawing at one cell while the canvas arrives at another moves every
+   * line under the reader on hydration.
+   */
+  getCellSizePx(): Promise<number>;
+  /**
+   * The line width, in pixels, as the component publishes it for the stand-in —
+   * `[lineWidth]`, floored at the 0.25px the canvas strokes at.
+   */
+  getLineWidthPx(): Promise<number>;
+  /**
+   * Whether the grid is hidden from assistive tech.
+   *
+   * A background canvas has nothing to announce, so losing this leaves a screen reader
+   * stopping on a nameless graphic in front of the section's actual content.
+   */
+  isDecorative(): Promise<boolean>;
+  /**
+   * Whether the drawing surface is in the markup.
+   *
+   * It is there in every state, including the ones where nothing is ever drawn on it —
+   * prerendered, no 2D context, reduced motion — so the stand-in has something to sit
+   * behind and {@link isPainted} has something to answer about.
+   */
+  hasCanvas(): Promise<boolean>;
+  private publishedPx;
+}
+export type { WrRippleGridHarnessFilters };

package/types/ngwr-bits-ripple-grid.d.ts

@@ -0,0 +1,294 @@
+import * as i0 from "@angular/core";
+/**
+ * Ripple-grid background — thin grid lines on a 2D canvas that the pointer
+ * sends ripples through. A press sends out a ring that travels outward, bends
+ * the lines it passes away from where it started and lights them in the ripple
+ * colour, and fades as it goes; with `rippleOnMove` a moving pointer leaves a
+ * trail of softer rings behind it. Fills its nearest positioned ancestor; put
+ * it behind hero copy or section content.
+ *
+ * With nothing pressed or moved the grid is still, and asks for no frames at
+ * all. `idleInterval` sends a softer ring out from the centre every so many
+ * milliseconds on its own; it is off by default, so a page that wants a grid
+ * which moves before anyone touches it asks for one. Each ring lives until it
+ * has faded or left the box, and never longer than six seconds.
+ *
+ * The pointer is followed on the host's PARENT, with passive listeners, so the
+ * grid answers a pointer that is over the content in front of it rather than
+ * over the canvas — the host itself takes no pointer events and never steals a
+ * click. Placed directly in a shadow root, where it has no parent element, it
+ * follows the pointer on the shadow host; with neither it listens nowhere, and
+ * only an idle ring ever moves it. Content placed after it needs
+ * `position: relative` (or any z-index) to paint above it, as with any
+ * absolutely positioned layer.
+ *
+ * The grid is laid out in the host's own box, before transforms, so one that
+ * boots inside a scaling-in panel (a dialog opening) is not stretched when the
+ * animation ends, and the pointer is mapped back through the transform.
+ *
+ * Decorative: the canvas is `aria-hidden`, the host has no role and nothing in
+ * it takes focus. The frame loop runs only while a ring is alive, and never
+ * while the host is off screen; an idle ring comes due only while frames run,
+ * so a hidden tab does not queue them up.
+ *
+ * Under `prefers-reduced-motion` one still grid is drawn, in the line colour,
+ * with no ripples, no idle rings and no pointer listeners; it is drawn again
+ * when an input, the box or the page's colour scheme changes. The preference
+ * is read live, and switching it on drops the rings already travelling.
+ *
+ * Colours are theme tokens by default — the lines `--wr-border-base`, the lit
+ * stretches `--wr-color-primary` — through the `--wr-ripple-grid-line-color`
+ * and `--wr-ripple-grid-ripple-color` hooks, and resolved before they reach
+ * the canvas, which reads neither a `var()` nor a `light-dark()`.
+ *
+ * Until the canvas has drawn — the seconds before hydration on a prerendered
+ * page — the stylesheet paints the same grid, at the same cell, width and
+ * colour, and `.wr-ripple-grid--painted` retires it.
+ *
+ * @example
+ * ```html
+ * <section style="position: relative; min-height: 24rem; overflow: hidden">
+ *   <wr-ripple-grid />
+ *   <h1 style="position: relative">Hero copy above the grid</h1>
+ * </section>
+ * ```
+ *
+ * @see https://ngwr.dev/bits/ripple-grid
+ */
+export declare class WrRippleGrid {
+  /** Distance between grid lines in px, never under 12. @default 40 */
+  readonly cellSize: import("@angular/core").InputSignalWithTransform<number, unknown>;
+  /** Line colour, any CSS colour. When unset, `--wr-ripple-grid-line-color` decides. */
+  readonly lineColor: import("@angular/core").InputSignal<string | null>;
+  /** Colour a line takes where a ripple passes, any CSS colour. When unset, `--wr-ripple-grid-ripple-color` decides. */
+  readonly rippleColor: import("@angular/core").InputSignal<string | null>;
+  /** Line width in px, never under 0.25. @default 1 */
+  readonly lineWidth: import("@angular/core").InputSignalWithTransform<number, unknown>;
+  /**
+   * How far a fresh ripple from a press bends the lines at its crest, in px;
+   * a ripple the moving pointer leaves bends them 40% as far. `0` keeps the
+   * lines straight and only lights them, and a negative value bends them
+   * inward. A bend steep enough to fold a line back over itself is never
+   * drawn: one ring, or several where they overlap, bends a line at most about
+   * 0.3 of a cell for cells from 22 to 80px — 11.7px at the default 40 — and
+   * rings that overlap share that bound rather than adding past it. @default 10
+   */
+  readonly strength: import("@angular/core").InputSignalWithTransform<number, unknown>;
+  /** How fast a ripple travels outward, in px per second; `0` keeps it where it started. @default 320 */
+  readonly speed: import("@angular/core").InputSignalWithTransform<number, unknown>;
+  /**
+   * How fast a ripple fades, per second: its strength is multiplied by
+   * `e^-decay` every second, so `1.4` halves it in half a second. `0` keeps it
+   * at full strength until it leaves the box. @default 1.4
+   */
+  readonly decay: import("@angular/core").InputSignalWithTransform<number, unknown>;
+  /** Whether a moving pointer leaves ripples behind it, and not only a press. @default true */
+  readonly rippleOnMove: import("@angular/core").InputSignalWithTransform<boolean, any>;
+  /**
+   * Milliseconds between the softer ripples sent out from the centre on their
+   * own, never under 500; `0` sends none, and the grid then stays still until
+   * the pointer moves it. @default 0
+   */
+  readonly idleInterval: import("@angular/core").InputSignalWithTransform<number, unknown>;
+  /** The cell the grid is laid out at: `cellSize`, floored. */
+  protected readonly cell: import("@angular/core").Signal<number>;
+  /** The line width drawn: `lineWidth`, floored. */
+  protected readonly stroke: import("@angular/core").Signal<number>;
+  /**
+   * A line colour the author chose, published so the stand-in draws in it too;
+   * `null` while the input is unset. On a variable of its own rather than on the
+   * hook, which an author sets from outside: a `null` binding wipes a value of its
+   * own name from the host's `style` attribute.
+   */
+  protected readonly standInColor: import("@angular/core").Signal<string | null>;
+  /** The colours the canvas resolves: an input that is unset, empty or blank leaves the hook in charge. */
+  private readonly lineExpression;
+  private readonly rippleExpression;
+  /** The idle interval in force, in ms; 0 when there is none. */
+  private readonly idle;
+  /** A ring's half-width, in px: a share of the cell, within bounds. */
+  private readonly ringWidth;
+  /**
+   * Flips once the canvas has drawn, which retires the CSS stand-in grid.
+   *
+   * A canvas cannot be prerendered, so on an SSR'd page it is blank until the
+   * bundle has loaded and hydrated. The stylesheet paints the same lines at the
+   * same cell from the prerendered HTML in the meantime, and this hands over.
+   */
+  protected readonly painted: import("@angular/core").WritableSignal<boolean>;
+  private readonly canvasRef;
+  private readonly host;
+  private readonly zone;
+  private readonly destroyRef;
+  private readonly platform;
+  private readonly isBrowser;
+  private ctx;
+  /** The host's layout box, in CSS pixels before any transform: what the grid is laid out in. */
+  private box;
+  /** Bitmap pixels per CSS pixel the canvas is backed at; 0 until the first fit. */
+  private ratio;
+  private readonly ripples;
+  private readonly pending;
+  /** The live rings as this frame draws them, reused frame to frame. */
+  private readonly rings;
+  private ringCount;
+  /** The rings that reach the line being traced, reused line to line. */
+  private readonly near;
+  /** Lit stretches by alpha step, reused frame to frame. */
+  private readonly lit;
+  private anyLit;
+  /** Where the last trail ripple was left, in viewport coordinates, while the pointer is over the parent. */
+  private readonly anchor;
+  /** The ring half-width and sample step this frame draws with, read once rather than per sample. */
+  private frameRing;
+  private frameStep;
+  /** One sample, displaced: written by `displace()`, read straight after. */
+  private sx;
+  private sy;
+  private sg;
+  private rafId;
+  private lastTime;
+  /** The frame callback, made once rather than a closure per frame. */
+  private readonly frame;
+  /** Whether the idle timer has fired and the next frame owes the centre a ring. */
+  private idleDue;
+  /** Schedules a frame while motion is allowed; `null` under reduced motion. */
+  private wake;
+  /** Arms the next idle ring while motion is allowed; `null` under reduced motion. */
+  private armIdle;
+  /** Flips once `boot()` has a context and a box — everything after waits for it. */
+  private readonly booted;
+  constructor();
+  private boot;
+  /** Follow the pointer, keep the idle timer and draw on demand; returns what stops all three. */
+  private interact;
+  /** Queue a ring at a viewport point for the next frame, and mark the point for the trail. */
+  private emit;
+  /** Draw the grid as it should look now: a frame while motion is allowed, at once under reduced motion. */
+  private requestDraw;
+  /** Fit the canvas to a new box or pixel ratio and, when that cleared it, repaint at once. */
+  private resize;
+  /**
+   * Back the canvas for a `width` × `height` box, in CSS pixels, at the screen's
+   * pixel ratio. Returns whether anything changed: writing `canvas.width` clears
+   * the bitmap even to the value it already has, so an unchanged box is left alone.
+   */
+  private fit;
+  /**
+   * Bitmap pixels per CSS pixel for a box of `area` CSS px². The screen's own
+   * ratio when it fits under 2 and the pixel budget, so a bitmap pixel is a
+   * device pixel and a snapped line lands on whole device pixels; otherwise the
+   * largest whole fraction of it that fits — a half, a third — so each bitmap
+   * pixel still covers a whole number of device pixels and every line keeps one
+   * weight. A ratio between (1.31 on a 2x screen) is resampled onto the screen
+   * by a fraction, which no snapping survives. Never below 1 on a 1x screen or
+   * better: a 1.5x screen past the budget takes 1 and accepts the resampling,
+   * rather than a bitmap coarser than the CSS box.
+   */
+  private pixelRatio;
+  /** No ring alive, none queued, none owed. */
+  private rest;
+  private tick;
+  /** Age every ring by `step` ms, place the queued ones, and retire the ones with nothing left to show. */
+  private advance;
+  /**
+   * Start a ring at a box point. Past `MAX_RIPPLES` it replaces the faintest live
+   * ring — the oldest of the faintest on a tie — so a press in the middle of a
+   * fast drag is not the one that vanishes; when every live ring is still
+   * stronger than this one starts out, this one is the faintest, and it is dropped.
+   */
+  private place;
+  /** How strong a ring still is, 0..1: its share, faded by `decay` and by the end of its life. */
+  private energy;
+  /**
+   * How far past each edge the lines run, so a bend never pulls a line's end into
+   * view: a cell, plus the most the rings at one point can bend it — the overlap
+   * budget, or every ring at full strength when that is less.
+   */
+  private margin;
+  private draw;
+  /**
+   * Work out where every live ring stands at its current age, for this frame's
+   * samples, and hold the rings that overlap to the bend budget together.
+   *
+   * Each ring's bend is scaled by its share of the budget against every ring
+   * whose band meets its own: wherever two rings both reach a point their bands
+   * meet, so the rings acting on any point add up to the budget at most (see
+   * `PUSH_PER_WIDTH`), while a ring that meets no other keeps its full bend. A
+   * pair counts in full once its bands meet and fades out over one half-width of
+   * gap before that, so two rings drifting into each other give way smoothly
+   * rather than both shrinking in one frame.
+   */
+  private prepareRings;
+  /**
+   * Add one grid line to the path — vertical at `x = fixed` or horizontal at
+   * `y = fixed`, from `from` to `to` along it — and file its lit stretches by
+   * alpha step. A line no ring reaches is two points; one a ring reaches is
+   * sampled only across the stretch the rings can bend, and straight either
+   * side of it. Where that stretch runs to an end of the line, the end is the
+   * displaced sample itself: drawing the undisplaced end before it would step
+   * the line back along itself.
+   */
+  private trace;
+  /**
+   * Where the grid point `(x, y)` is drawn and how lit it is, with the first
+   * `count` rings in `near` acting on it; written to `sx`, `sy` and `sg`.
+   *
+   * Each ring pushes the point along the line from its origin. The push is a
+   * bell around the crest, shaped by a cosine so the crest bends outward and a
+   * shallow trough either side bends back in — what reads as a ripple rather
+   * than a bulge — and eased in over the first half-width, so the lines through
+   * the origin itself do not tear. The glow is the bell alone. Overlapping rings
+   * add up; `prepareRings()` has already held them to a budget that cannot fold
+   * the grid, so nothing is clamped here.
+   */
+  private displace;
+  static ɵfac: i0.ɵɵFactoryDeclaration<WrRippleGrid, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<WrRippleGrid, "wr-ripple-grid", never, {
+    "cellSize": {
+      "alias": "cellSize";
+      "required": false;
+      "isSignal": true;
+    };
+    "lineColor": {
+      "alias": "lineColor";
+      "required": false;
+      "isSignal": true;
+    };
+    "rippleColor": {
+      "alias": "rippleColor";
+      "required": false;
+      "isSignal": true;
+    };
+    "lineWidth": {
+      "alias": "lineWidth";
+      "required": false;
+      "isSignal": true;
+    };
+    "strength": {
+      "alias": "strength";
+      "required": false;
+      "isSignal": true;
+    };
+    "speed": {
+      "alias": "speed";
+      "required": false;
+      "isSignal": true;
+    };
+    "decay": {
+      "alias": "decay";
+      "required": false;
+      "isSignal": true;
+    };
+    "rippleOnMove": {
+      "alias": "rippleOnMove";
+      "required": false;
+      "isSignal": true;
+    };
+    "idleInterval": {
+      "alias": "idleInterval";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}

package/types/ngwr-bits-splash-cursor.d.ts

@@ -158,5 +158,4 @@ interface WrFluidConfig {
   /** Fixed splat colour (hex) when `rainbow` is off. */
   readonly color: string;
 }
-declare function createFluidSimulation(canvas: HTMLCanvasElement, config: WrFluidConfig): (() => void) | null;
 export type { WrFluidConfig };

package/types/ngwr-bits-spotlight-card-testing.d.ts

@@ -102,7 +102,9 @@ export declare class WrSpotlightCardHarness extends ComponentHarness {
    */
   getRadiusPercent(): Promise<number>;
   /**
-   * The highlight colour the author asked for, or `null` when they left it to the theme.
+   * The colour `[spotlightColor]` published on the host, or `null` when the input is unset.
+   * The `--wr-spotlight-color` hook then decides, which is the theme's value unless the
+   * author set it; this method does not read the hook.
    *
    * `null` IS the contract for an unset `[spotlightColor]`, not a gap in it. The
    * stylesheet's own default is a `light-dark()` over `--wr-color-on-surface`, and that