@link-foundation/ui-animation 0.0.0-stage → 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/LICENSE +24 -0
  2. package/README.md +454 -2
  3. package/package.json +77 -4
  4. package/src/backgrounds/README.md +131 -0
  5. package/src/backgrounds/beams.d.ts +21 -0
  6. package/src/backgrounds/beams.js +140 -0
  7. package/src/backgrounds/common.d.ts +23 -0
  8. package/src/backgrounds/common.js +322 -0
  9. package/src/backgrounds/grid.d.ts +16 -0
  10. package/src/backgrounds/grid.js +122 -0
  11. package/src/backgrounds/nebula.d.ts +9 -0
  12. package/src/backgrounds/nebula.js +57 -0
  13. package/src/backgrounds/rain-cleanup.js +77 -0
  14. package/src/backgrounds/rain.d.ts +33 -0
  15. package/src/backgrounds/rain.js +238 -0
  16. package/src/backgrounds/shader.d.ts +14 -0
  17. package/src/backgrounds/shader.js +151 -0
  18. package/src/backgrounds/sprites.js +72 -0
  19. package/src/backgrounds/starfield.d.ts +38 -0
  20. package/src/backgrounds/starfield.js +168 -0
  21. package/src/clock.js +98 -0
  22. package/src/compile-waapi.js +147 -0
  23. package/src/diagnostics.js +51 -0
  24. package/src/easing.js +327 -0
  25. package/src/effects/decipher.js +83 -0
  26. package/src/effects.js +44 -0
  27. package/src/index.d.ts +581 -0
  28. package/src/index.js +74 -0
  29. package/src/layers.js +88 -0
  30. package/src/model.js +636 -0
  31. package/src/player.js +267 -0
  32. package/src/random.js +62 -0
  33. package/src/recorder/buffer.js +40 -0
  34. package/src/recorder/clock.js +2 -0
  35. package/src/recorder/format.js +125 -0
  36. package/src/recorder/input.js +53 -0
  37. package/src/recorder/recorder.js +183 -0
  38. package/src/recorder/redact.js +43 -0
  39. package/src/recorder/replay.js +115 -0
  40. package/src/recorder/state-at.js +62 -0
  41. package/src/recorder/store.js +92 -0
  42. package/src/recorder/to-playwright.js +113 -0
  43. package/src/recorder/verify.js +49 -0
  44. package/src/run.js +283 -0
  45. package/src/sample.js +160 -0
  46. package/src/timeline.js +115 -0
  47. package/src/timing.js +172 -0
  48. package/src/tokens.js +32 -0
  49. package/src/types.js +130 -0
  50. package/src/validate.js +218 -0
  51. package/src/values.js +331 -0
@@ -0,0 +1,131 @@
1
+ # Decorative background layers
2
+
3
+ Each entry point exports `mount(target, options)` and returns
4
+ `{ update(partial), animate(on), dispose() }`. Import only the effects you use:
5
+
6
+ ```js
7
+ import { mount } from '@link-foundation/ui-animation/backgrounds/starfield';
8
+ const stars = mount(canvas, { count: 500, motion: 'drift', seed: 'sky' });
9
+ stars.update({ color: '#b0ccff' });
10
+ stars.animate(false);
11
+ stars.dispose();
12
+ ```
13
+
14
+ Use `backgrounds/shader`, `backgrounds/beams`, `backgrounds/rain` and
15
+ `backgrounds/grid` in the same way. Grid mounts on a positioned div; the others
16
+ mount on separate canvases. Hosts own positioning and the CSS fallback. Give
17
+ each target `position: fixed; inset: 0; width: 100%; height: 100%`, inside an
18
+ isolated stacking context. Stack up to four star canvases for independent looks.
19
+ `order` controls z-index; `level` is 0..2 (CSS opacity saturates at 1). Grid level
20
+ is 0..4 and maps to opacity 0..1.
21
+
22
+ The runnable [all-layer example](../../../../examples/animation/backgrounds/)
23
+ loads its appearance from nested Links Notation using the official parser.
24
+ Serve with `node scripts/serve-static.mjs` and open
25
+ `http://127.0.0.1:4173/examples/animation/backgrounds/`.
26
+
27
+ ## Shared lifecycle
28
+
29
+ Options: `animate` (true), `fps` (5..60, default 60), `dprCap` (2), `level` (1),
30
+ `order` (0), `lightScheme` (false), `lightOpacity` (0.65), `adaptive` (true).
31
+ WebGL also accepts `resolution` (0.2..1). `lightScheme` follows the system's
32
+ light preference and applies `invert(1) hue-rotate(180deg)` and `lightOpacity`.
33
+ An explicit `reducedMotion` boolean overrides the media query. Targets are
34
+ aria-hidden, ignore pointer events and disappear in print.
35
+
36
+ Mount renders once. ResizeObserver corrects late CSS sizing; window resize
37
+ checks zoom/monitor DPR changes. Identical sizes and changes to unknown metadata
38
+ or fps do not repaint. Pausing cancels scheduled frames without clearing. Resume
39
+ resets the elapsed-time origin and continues the same model. Live visual updates
40
+ repaint even while paused; hidden updates wait until the document is visible.
41
+ Dispose is idempotent and removes observers, subscriptions, GPU objects and rain
42
+ filters. Missing required graphics APIs or shader compile/link failure yields an
43
+ inert handle and hides that canvas so the host's fallback remains visible.
44
+ `onError(error)` optionally receives graphics initialization errors.
45
+
46
+ Layers register with `createEffectGovernor`. By default each owns its governor;
47
+ pass `governor` to share an existing instance, whose motion state remains host
48
+ owned. Local preference/visibility gates unsubscribe inactive layers. Local fps
49
+ limits and synchronous zero-elapsed invalidation complement the governor's
50
+ adaptive quality shares. Shares never increase during a layer's lifetime. Slow raw display gaps (>45 ms) are judged after a warm-up
51
+ in windows of 30 frames or 1 s. WebGL resolution falls by 0.7 to 0.4, then fps
52
+ halves to 0.25; crisp layers lower fps only. Disable with `adaptive: false`.
53
+ The governor supplies elapsed seconds and `{scale, fps}` as callback arguments.
54
+ The injectable `environment` supplies browser APIs for deterministic tests.
55
+
56
+ ## Sprite starfield
57
+
58
+ `count` (160) is per 1920×1080, range 0..3000, area-scaled and capped at 6000.
59
+ `seed` fixes the sequence. Shapes: `dot`, `soft-dot`, `ring`, `square`, `diamond`,
60
+ `cross`, `cross-x`, `star-4`, `star-5`, `star-6`, `sparkle`, `telescope-flare`.
61
+
62
+ Look controls: `size` (0.5..24), `sizeSpread` (0..1), `color`, `hueSpread`
63
+ (0..180 degrees), `brightness` (0..1), `glow` (0..40), `glowColor`,
64
+ `twinkleRate` (0..5), `twinkleDepth` (0..1), `rotation` (0..180 degrees),
65
+ `spin` (-180..180 degrees/second), `streak` (0..20), `blend`
66
+ (`normal`, `add`, `screen`). Nine hue sprites are cached per look/DPR. Colour
67
+ changes rebuild sprites and retain positions. Count changes retain the seeded
68
+ prefix. `motion` is `still`, `drift`, `warp` or `orbit`; `direction` is degrees
69
+ and `speed` is 0..400 CSS px/s. Nearer stars travel faster.
70
+
71
+ ## Shader backdrop and original nebula
72
+
73
+ `source` is a WebGL 1 fragment shader. The full-screen triangle mesh supplies
74
+ `position`. Uniforms `resolution` (backing pixels), `pixelRatio` and `time` are
75
+ provided. `uniforms` maps names to numbers, `#rrggbb` colours or `{degrees: n}`.
76
+ `times` maps named time uniforms to speeds (default `{time: 1}`); every clock
77
+ integrates independently, so changing a speed never jumps. `startTime` is a
78
+ number or `random` (a seeded offset). Update uniform/time maps with complete
79
+ replacement maps. Failed live shader replacement hides the canvas until a valid
80
+ source is supplied. The context requests low power, opaque output and no MSAA.
81
+
82
+ ```js
83
+ import { mount } from '@link-foundation/ui-animation/backgrounds/shader';
84
+ import { nebula } from '@link-foundation/ui-animation/backgrounds/nebula';
85
+ const options = nebula({ driftSpeed: 1, twinkleSpeed: 1 });
86
+ const sky = mount(canvas, options);
87
+ sky.update({ times: { time: 2, twinkleTime: 0.5 } });
88
+ ```
89
+
90
+ The original analytic nebula supports `gas` (0..2.5), `hue` (degrees, -180..180),
91
+ `starDensity` (0..4), `starBrightness` (0..2.5), `twinkle` (0..5), `vignette`
92
+ (0..1), `zoom` (0.3..3), `gasColor1` through `gasColor4`, `starColor` and
93
+ `starSize` (0.5..3). `driftSpeed` is 0..8. Artwork-specific host shaders stay
94
+ host content.
95
+
96
+ ## Grid-line beams
97
+
98
+ `cellSize` (64), `style` (`comet`, `segment`, `pulse`, `scan`), `direction`
99
+ (`horizontal`, `vertical`, `both`), `bothSenses` (true), `count` (1..40),
100
+ `speed` (20..1500 CSS px/s, each beam 0.75..1.25×), `length` (10..800), `width`
101
+ (0.5..8), `color`, `glow` (0..40 device px), `pause` (0..10 s), `snap` (true),
102
+ `drift` (CSS px). Geometry/direction changes reseed; appearance updates retain
103
+ paths. Reduced motion places beams along their seeded paths.
104
+
105
+ ## Glyph rain
106
+
107
+ `paint(ctx, glyph, x, y, size, glow)` and `pick()` let the host supply its own
108
+ artwork. Default glyphs are seeded digits painted with monospace text.
109
+ `cellSize` (64) gives two columns per cell; `step` is 20..400 ms; `columnSteps`
110
+ is 1..8; `density` is 0.05..1; `restart` is 0.005..0.5; `fade` is 0.01..0.5;
111
+ `glow` is 0..40 device px; `padding` is 0..16, capped at 3/8 cell; `color`,
112
+ `visible` and `drift` update live. `visible: false` leaves drift running.
113
+
114
+ Cadence uses the median of the last 30 display gaps below 100 ms, rounds the
115
+ step to whole frames and never catches up multiple steps in one frame. A 105 ms
116
+ step is every 6 frames at 60 Hz and 13 at 120 Hz. Destination-out fading keeps
117
+ the canvas transparent. Old heads are repainted without glow. About once per
118
+ second an SVG alpha table clears values ≤9/255; a pixel pass covers engines
119
+ without working SVG filters. Reduced motion paints a deterministic static field
120
+ with alpha 0.2..0.8.
121
+
122
+ ## Grid pattern and registration
123
+
124
+ `cellSize` (32..128), `lineWidth` (0.5..4), `markLength` (0.05..1), `pattern`
125
+ (`lines`, `dashed`, `crosses`, `dots`), `level` (0..4), `tint` (`line`, `accent`,
126
+ `second-accent`, `custom`), `color`, `radialFade`, `period` (0..120 s, 0 still).
127
+ Theme tints use `--color-line`, `--color-accent` and `--color-accent-2`.
128
+
129
+ The CSS pattern is one extra cell tall. `onDrift(px)` receives the shared offset;
130
+ forward it to rain and beams with `update({drift: px})`. At a wrap, the offset
131
+ shifts by exactly one cell. See the example's wiring.
@@ -0,0 +1,21 @@
1
+ import type { CommonOptions, LayerHandle } from './common.js';
2
+ export interface BeamOptions extends CommonOptions {
3
+ seed?: number | string;
4
+ cellSize?: number;
5
+ style?: 'comet' | 'segment' | 'pulse' | 'scan';
6
+ direction?: 'horizontal' | 'vertical' | 'both';
7
+ bothSenses?: boolean;
8
+ count?: number;
9
+ speed?: number;
10
+ length?: number;
11
+ width?: number;
12
+ color?: string;
13
+ glow?: number;
14
+ pause?: number;
15
+ snap?: boolean;
16
+ drift?: number;
17
+ }
18
+ export function mount(
19
+ canvas: HTMLCanvasElement,
20
+ options?: BeamOptions
21
+ ): LayerHandle<BeamOptions>;
@@ -0,0 +1,140 @@
1
+ import { seededRandom } from '../random.js';
2
+ import { mountLayer, changed, clamp, bounded } from './common.js';
3
+
4
+ const defaults = {
5
+ seed: 224,
6
+ cellSize: 64,
7
+ style: 'comet',
8
+ direction: 'both',
9
+ bothSenses: true,
10
+ count: 8,
11
+ speed: 120,
12
+ length: 180,
13
+ width: 1,
14
+ color: '#88bbff',
15
+ glow: 12,
16
+ pause: 1,
17
+ snap: true,
18
+ drift: 0,
19
+ };
20
+ function create(canvas) {
21
+ const ctx = canvas.getContext('2d');
22
+ if (!ctx) {
23
+ return null;
24
+ }
25
+ let o,
26
+ area,
27
+ beams = [];
28
+ function seed() {
29
+ const random = seededRandom(o.seed);
30
+ beams = Array.from({ length: Math.round(clamp(o.count, 1, 40)) }, () => ({
31
+ vertical:
32
+ o.direction === 'vertical' ||
33
+ (o.direction === 'both' && random() > 0.5),
34
+ line: random(),
35
+ position: random(),
36
+ speed: 0.75 + random() * 0.5,
37
+ sense: o.bothSenses && random() > 0.5 ? -1 : 1,
38
+ wait: 0,
39
+ }));
40
+ }
41
+ function drawTrail(b, head) {
42
+ const tail = head - b.sense * o.length;
43
+ const gradient = ctx.createLinearGradient(tail, 0, head || 0.001, 0);
44
+ gradient.addColorStop(0, o.style === 'segment' ? o.color : 'transparent');
45
+ gradient.addColorStop(o.style === 'pulse' ? 0.5 : 1, o.color);
46
+ if (o.style === 'pulse') {
47
+ gradient.addColorStop(1, 'transparent');
48
+ }
49
+ ctx.strokeStyle = gradient;
50
+ ctx.beginPath();
51
+ ctx.moveTo(tail, 0);
52
+ ctx.lineTo(head, 0);
53
+ ctx.stroke();
54
+ }
55
+ function drawBeam(b, dt, still) {
56
+ const extent = b.vertical ? area.height : area.width;
57
+ if (!still && b.wait > 0) {
58
+ b.wait -= dt;
59
+ return;
60
+ }
61
+ if (!still) {
62
+ b.position += (o.speed * b.speed * dt) / extent;
63
+ }
64
+ if (b.position > 1 + o.length / extent) {
65
+ b.position = -o.length / extent;
66
+ b.wait = o.pause;
67
+ }
68
+ const across = b.line * (b.vertical ? area.width : area.height);
69
+ const line =
70
+ (o.snap ? Math.round(across / o.cellSize) * o.cellSize : across) +
71
+ (b.vertical ? 0 : o.drift);
72
+ const head = b.sense > 0 ? b.position * extent : (1 - b.position) * extent;
73
+ ctx.save();
74
+ if (b.vertical) {
75
+ ctx.translate(line, 0);
76
+ ctx.rotate(Math.PI / 2);
77
+ } else {
78
+ ctx.translate(0, line);
79
+ }
80
+ ctx.shadowColor = o.color;
81
+ ctx.shadowBlur = o.glow;
82
+ ctx.lineWidth = o.width;
83
+ if (o.style === 'scan') {
84
+ const acrossExtent = b.vertical ? area.width : area.height;
85
+ ctx.fillStyle = o.color;
86
+ ctx.fillRect(head, -acrossExtent, o.width, acrossExtent * 2);
87
+ } else {
88
+ drawTrail(b, head);
89
+ }
90
+ ctx.restore();
91
+ }
92
+ return {
93
+ defaults,
94
+ update(next, before) {
95
+ o = bounded(next, {
96
+ cellSize: [32, 128],
97
+ count: [1, 40],
98
+ speed: [20, 1500],
99
+ length: [10, 800],
100
+ width: [0.5, 8],
101
+ glow: [0, 40],
102
+ pause: [0, 10],
103
+ });
104
+ if (
105
+ area &&
106
+ changed(next, before, [
107
+ 'cellSize',
108
+ 'direction',
109
+ 'bothSenses',
110
+ 'seed',
111
+ 'snap',
112
+ ])
113
+ ) {
114
+ seed();
115
+ } else if (area && next.count !== before.count) {
116
+ const current = beams;
117
+ seed();
118
+ beams = beams.map((beam, i) => current[i] ?? beam);
119
+ }
120
+ return changed(
121
+ next,
122
+ before,
123
+ Object.keys(defaults).filter((key) => !['speed', 'pause'].includes(key))
124
+ );
125
+ },
126
+ resize(next, old) {
127
+ area = next;
128
+ if (!old) {
129
+ seed();
130
+ }
131
+ },
132
+ draw(dt, { still }) {
133
+ ctx.setTransform(area.ratio, 0, 0, area.ratio, 0, 0);
134
+ ctx.clearRect(0, 0, area.width, area.height);
135
+ beams.forEach((b) => drawBeam(b, dt, still));
136
+ },
137
+ };
138
+ }
139
+ export const mount = (canvas, options = {}) =>
140
+ mountLayer(canvas, options, create);
@@ -0,0 +1,23 @@
1
+ import type { createEffectGovernor } from '@link-foundation/ui-themes/classic/materials';
2
+
3
+ export interface LayerHandle<Options = CommonOptions> {
4
+ update(partial: Partial<Options>): void;
5
+ animate(on: boolean): void;
6
+ dispose(): void;
7
+ }
8
+ export interface CommonOptions {
9
+ animate?: boolean;
10
+ fps?: number;
11
+ dprCap?: number;
12
+ /** WebGL only, 0.2..1. */
13
+ resolution?: number;
14
+ adaptive?: boolean;
15
+ level?: number;
16
+ order?: number;
17
+ lightScheme?: boolean;
18
+ lightOpacity?: number;
19
+ reducedMotion?: boolean;
20
+ environment?: Window;
21
+ onError?: (error: unknown) => void;
22
+ governor?: Pick<ReturnType<typeof createEffectGovernor>, 'add'>;
23
+ }
@@ -0,0 +1,322 @@
1
+ import { createEffectGovernor } from '@link-foundation/ui-themes/classic/materials';
2
+
3
+ let nextLayerId = 0;
4
+
5
+ export const clamp = (value, min, max) =>
6
+ Math.max(min, Math.min(max, Number(value) || 0));
7
+ export const bounded = (options, ranges) => ({
8
+ ...options,
9
+ ...Object.fromEntries(
10
+ Object.entries(ranges).map(([key, [min, max]]) => [
11
+ key,
12
+ clamp(options[key], min, max),
13
+ ])
14
+ ),
15
+ });
16
+ export const radians = (degrees) => (Number(degrees) * Math.PI) / 180;
17
+ export const noop = () => ({ update() {}, animate() {}, dispose() {} });
18
+ export const changed = (a, b, keys) => keys.some((key) => a[key] !== b[key]);
19
+
20
+ function decorate(canvas, options) {
21
+ canvas.setAttribute('aria-hidden', 'true');
22
+ canvas.setAttribute('data-ui-background', '');
23
+ Object.assign(canvas.style, {
24
+ pointerEvents: 'none',
25
+ opacity: String(clamp(options.level, 0, options.maxLevel ?? 2)),
26
+ zIndex: String(options.order),
27
+ filter: options.lightScheme ? 'invert(1) hue-rotate(180deg)' : '',
28
+ });
29
+ if (options.lightScheme) {
30
+ canvas.style.opacity = String(
31
+ clamp(options.level, 0, 2) * clamp(options.lightOpacity, 0, 1)
32
+ );
33
+ }
34
+ }
35
+
36
+ function printStyle(doc) {
37
+ if (!doc || doc.querySelector?.('style[data-ui-background-print]')) {
38
+ return;
39
+ }
40
+ const style = doc.createElement('style');
41
+ style.setAttribute('data-ui-background-print', '');
42
+ style.textContent =
43
+ '@media print { [data-ui-background] { display: none !important; } }';
44
+ doc.head?.append(style);
45
+ }
46
+
47
+ function subscriptions(s) {
48
+ const { win, doc, media, light } = s;
49
+ const visibility = () => {
50
+ s.sync();
51
+ };
52
+ const preference = () => {
53
+ s.driver.invalidate?.();
54
+ s.repaint();
55
+ s.sync();
56
+ };
57
+ const resize = () => s.resize();
58
+ doc?.addEventListener('visibilitychange', visibility);
59
+ media?.addEventListener('change', preference);
60
+ light?.addEventListener('change', preference);
61
+ win.addEventListener?.('resize', resize);
62
+ const observer = win.ResizeObserver ? new win.ResizeObserver(resize) : null;
63
+ observer?.observe(s.canvas);
64
+ return () => {
65
+ observer?.disconnect();
66
+ doc?.removeEventListener('visibilitychange', visibility);
67
+ media?.removeEventListener('change', preference);
68
+ light?.removeEventListener('change', preference);
69
+ win.removeEventListener?.('resize', resize);
70
+ };
71
+ }
72
+
73
+ function lifecycle(s) {
74
+ const quality = { scale: 1, fps: 1 };
75
+ let remove,
76
+ adaptive,
77
+ previous = null,
78
+ lastDraw = null;
79
+ const active = () => s.options.animate && !s.doc?.hidden && !s.reduced();
80
+ const reset = () => {
81
+ previous = lastDraw = null;
82
+ s.driver.resetClock?.();
83
+ };
84
+ const tick = (time, _state, elapsed, shares = { scale: 1, fps: 1 }) => {
85
+ if (elapsed === 0) {
86
+ previous = lastDraw = null;
87
+ }
88
+ const gap = previous === null ? 0 : time - previous;
89
+ previous = time;
90
+ if (s.options.adaptive) {
91
+ quality.scale = Math.min(quality.scale, shares.scale);
92
+ quality.fps = Math.min(quality.fps, shares.fps);
93
+ }
94
+ if (s.scale !== quality.scale) {
95
+ s.scale = quality.scale;
96
+ s.resize();
97
+ }
98
+ s.driver.frame?.(gap);
99
+ const fps = clamp(s.options.fps, 5, 60) * quality.fps;
100
+ const ready = s.driver.cadence
101
+ ? gap > 0 && s.driver.cadence(fps)
102
+ : lastDraw === null || time - lastDraw + 0.01 >= 1000 / fps;
103
+ if (ready) {
104
+ const dt =
105
+ lastDraw === null ? 0 : clamp((time - lastDraw) / 1000, 0, 0.25);
106
+ lastDraw = time;
107
+ s.draw(dt, true);
108
+ }
109
+ return true;
110
+ };
111
+ s.sync = () => {
112
+ if (remove && (!active() || adaptive !== s.options.adaptive)) {
113
+ remove();
114
+ remove = null;
115
+ reset();
116
+ }
117
+ if (!remove && active()) {
118
+ reset();
119
+ adaptive = s.options.adaptive;
120
+ // Keep full display cadence for rain's measured-frame quantization.
121
+ // The governor owns adaptive shares; the layer applies its live fps cap.
122
+ remove = s.governor.add(s.id, tick, {
123
+ resolution: s.driver.webgl === true,
124
+ minScale: adaptive ? 0.4 : 1,
125
+ minFps: adaptive ? 0.25 : 1,
126
+ });
127
+ }
128
+ if (!s.doc?.hidden && s.dirty) {
129
+ s.repaint();
130
+ }
131
+ };
132
+ return () => {
133
+ remove?.();
134
+ reset();
135
+ };
136
+ }
137
+
138
+ function rendering(s) {
139
+ s.reduced = () => s.options.reducedMotion ?? s.media?.matches ?? false;
140
+ s.draw = (dt = 0, frame = false) => {
141
+ if (s.disposed || s.doc?.hidden) {
142
+ s.dirty = true;
143
+ return;
144
+ }
145
+ s.driver.draw(dt, {
146
+ ...s.size,
147
+ still: s.reduced(),
148
+ options: s.options,
149
+ frame,
150
+ });
151
+ s.dirty = false;
152
+ };
153
+ s.repaint = () => {
154
+ decorate(s.canvas, {
155
+ ...s.options,
156
+ level: s.driver.css ? 1 : s.options.level,
157
+ lightScheme: s.options.lightScheme && s.light?.matches,
158
+ });
159
+ s.draw();
160
+ };
161
+ s.resize = () => {
162
+ const rect = s.canvas.getBoundingClientRect();
163
+ const dpr = Math.min(
164
+ s.win.devicePixelRatio || 1,
165
+ clamp(s.options.dprCap, 0.1, 8)
166
+ );
167
+ const ratio =
168
+ dpr *
169
+ (s.driver.webgl ? clamp(s.options.resolution * s.scale, 0.2, 1) : 1);
170
+ const width = Math.max(1, Math.round(rect.width * ratio));
171
+ const height = Math.max(1, Math.round(rect.height * ratio));
172
+ const next = { width: rect.width, height: rect.height, dpr, ratio };
173
+ if (
174
+ s.size &&
175
+ !changed(s.size, next, Object.keys(next)) &&
176
+ (s.driver.css || (s.canvas.width === width && s.canvas.height === height))
177
+ ) {
178
+ return;
179
+ }
180
+ const old = s.size;
181
+ s.size = next;
182
+ if (!s.driver.css) {
183
+ s.canvas.width = width;
184
+ s.canvas.height = height;
185
+ }
186
+ s.driver.resize(next, old);
187
+ s.repaint();
188
+ };
189
+ }
190
+
191
+ function createDriver(canvas, win, options, create) {
192
+ let driver;
193
+ try {
194
+ driver = create(canvas, win, options);
195
+ } catch (error) {
196
+ options.onError?.(error);
197
+ }
198
+ if (!driver) {
199
+ if (canvas?.style) {
200
+ canvas.style.visibility = 'hidden';
201
+ }
202
+ return null;
203
+ }
204
+ return driver;
205
+ }
206
+
207
+ function initialize(s, stop, options) {
208
+ const { driver, canvas } = s;
209
+ try {
210
+ driver.update(s.options, {});
211
+ s.resize();
212
+ s.sync();
213
+ } catch (error) {
214
+ stop();
215
+ driver.dispose?.();
216
+ if (!options.governor) {
217
+ s.governor.dispose();
218
+ }
219
+ canvas.style.visibility = 'hidden';
220
+ options.onError?.(error);
221
+ return false;
222
+ }
223
+ return true;
224
+ }
225
+
226
+ /** Internal shared mount: each effect supplies only its drawing/model driver. */
227
+ export function mountLayer(canvas, options, create) {
228
+ const doc = canvas?.ownerDocument;
229
+ const win = options.environment ?? doc?.defaultView ?? globalThis;
230
+ canvas?.setAttribute('aria-hidden', 'true');
231
+ canvas?.setAttribute('data-ui-background', '');
232
+ if (canvas?.style) {
233
+ canvas.style.pointerEvents = 'none';
234
+ }
235
+ printStyle(doc);
236
+ const driver = createDriver(canvas, win, options, create);
237
+ if (!driver) {
238
+ return noop();
239
+ }
240
+ const s = {
241
+ canvas,
242
+ doc,
243
+ win,
244
+ driver,
245
+ id: `ui-background-${++nextLayerId}`,
246
+ scale: 1,
247
+ dirty: false,
248
+ disposed: false,
249
+ options: {
250
+ animate: true,
251
+ fps: 60,
252
+ dprCap: 2,
253
+ resolution: 1,
254
+ adaptive: true,
255
+ level: 1,
256
+ order: 0,
257
+ lightScheme: false,
258
+ lightOpacity: 0.65,
259
+ reducedMotion: undefined,
260
+ ...driver.defaults,
261
+ ...options,
262
+ },
263
+ media: win.matchMedia?.('(prefers-reduced-motion: reduce)'),
264
+ light: win.matchMedia?.('(prefers-color-scheme: light)'),
265
+ };
266
+ s.governor =
267
+ options.governor ??
268
+ createEffectGovernor({
269
+ requestFrame: (fn) => win.requestAnimationFrame(fn),
270
+ cancelFrame: (id) => win.cancelAnimationFrame(id),
271
+ });
272
+ if (!options.governor) {
273
+ s.governor.set({ motion: true });
274
+ }
275
+ rendering(s);
276
+ const stop = lifecycle(s);
277
+ if (!initialize(s, stop, options)) {
278
+ return noop();
279
+ }
280
+ const unsubscribe = subscriptions(s);
281
+ return {
282
+ update(partial) {
283
+ if (s.disposed) {
284
+ return;
285
+ }
286
+ const before = s.options;
287
+ s.options = { ...before, ...partial };
288
+ const visual = driver.update(s.options, before);
289
+ const commonVisual = changed(before, s.options, [
290
+ 'level',
291
+ 'order',
292
+ 'lightScheme',
293
+ 'lightOpacity',
294
+ 'reducedMotion',
295
+ ]);
296
+ if (changed(before, s.options, ['dprCap', 'resolution'])) {
297
+ s.resize();
298
+ } else if (visual || commonVisual) {
299
+ s.repaint();
300
+ }
301
+ s.sync();
302
+ },
303
+ animate(on) {
304
+ if (!s.disposed) {
305
+ s.options.animate = Boolean(on);
306
+ s.sync();
307
+ }
308
+ },
309
+ dispose() {
310
+ if (s.disposed) {
311
+ return;
312
+ }
313
+ s.disposed = true;
314
+ stop();
315
+ unsubscribe();
316
+ driver.dispose?.();
317
+ if (!options.governor) {
318
+ s.governor.dispose();
319
+ }
320
+ },
321
+ };
322
+ }
@@ -0,0 +1,16 @@
1
+ import type { CommonOptions, LayerHandle } from './common.js';
2
+ export interface GridOptions extends CommonOptions {
3
+ cellSize?: number;
4
+ lineWidth?: number;
5
+ markLength?: number;
6
+ pattern?: 'lines' | 'dashed' | 'crosses' | 'dots';
7
+ tint?: 'line' | 'accent' | 'second-accent' | 'custom';
8
+ color?: string;
9
+ radialFade?: boolean;
10
+ period?: number;
11
+ onDrift?: (px: number) => void;
12
+ }
13
+ export function mount(
14
+ element: HTMLElement,
15
+ options?: GridOptions
16
+ ): LayerHandle<GridOptions>;