@link-foundation/ui-animation 0.0.0 → 0.2.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.
package/README.md CHANGED
@@ -452,4 +452,5 @@ Replay or move the labelled time scrubber. The `<pre>` shows the sharable LiNo.
452
452
 
453
453
  Independent decorative canvas, WebGL and CSS entry points are documented in
454
454
  [backgrounds](src/backgrounds/README.md), with a runnable all-layer example,
455
- original nebula preset, host glyph hooks and reduced-motion/CSS fallbacks.
455
+ original nebula preset, host artwork and clock hooks, and reduced-motion/CSS
456
+ fallbacks.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@link-foundation/ui-animation",
3
- "version": "0.0.0",
3
+ "version": "0.2.0",
4
4
  "description": "Animations of the associative UI framework written in Links Notation: a declarative model of keyframe tracks, easings, springs, timelines and state triggers, a pure seeded sampler, safety validators and a WAAPI player",
5
5
  "type": "module",
6
6
  "exports": {
@@ -63,12 +63,12 @@
63
63
  "node": ">=20"
64
64
  },
65
65
  "dependencies": {
66
- "@link-foundation/ui-core": "^0.0.0",
67
- "@link-foundation/ui-store": "^0.0.0",
68
- "@link-foundation/ui-themes": "^0.0.0"
66
+ "@link-foundation/ui-core": "^0.1.0",
67
+ "@link-foundation/ui-store": "^0.1.0",
68
+ "@link-foundation/ui-themes": "^0.2.0"
69
69
  },
70
70
  "devDependencies": {
71
- "@link-foundation/ui-tokens": "^0.0.0",
71
+ "@link-foundation/ui-tokens": "^0.1.0",
72
72
  "esbuild": "0.27.0",
73
73
  "jsdom": "^30.1.3",
74
74
  "test-anywhere": "^0.8.48"
@@ -68,6 +68,14 @@ changes rebuild sprites and retain positions. Count changes retain the seeded
68
68
  prefix. `motion` is `still`, `drift`, `warp` or `orbit`; `direction` is degrees
69
69
  and `speed` is 0..400 CSS px/s. Nearer stars travel faster.
70
70
 
71
+ For host artwork, pass `random(seed)` to return a repeatable stream.
72
+ `layout({ count, width, height, dpr, random, options })` can use that stream and
73
+ return normalized positions with optional sprite indices, scale, opacity, and
74
+ rotation in degrees. `createSprites({ canvas, dpr, options })` returns
75
+ `{ image, size }` entries with their destination sizes in CSS pixels. A color or
76
+ sprite update keeps existing positions. Resizing the CSS bounds restarts
77
+ the layout callback's stream from the supplied seed.
78
+
71
79
  ## Shader backdrop and original nebula
72
80
 
73
81
  `source` is a WebGL 1 fragment shader. The full-screen triangle mesh supplies
@@ -79,6 +87,13 @@ number or `random` (a seeded offset). Update uniform/time maps with complete
79
87
  replacement maps. Failed live shader replacement hides the canvas until a valid
80
88
  source is supplied. The context requests low power, opaque output and no MSAA.
81
89
 
90
+ `startTime` also accepts a map of clock names to offsets. Pass `random(seed)`
91
+ to use host random state. Random start offsets call it with a seed qualified
92
+ by clock name (`${seed}:${name}`). `update({ clock: { time: seconds } })`
93
+ renders host time even while paused. Remove the override with `clock: {}` to
94
+ resume internal integration from that position. Register the uniform in
95
+ `times` first.
96
+
82
97
  ```js
83
98
  import { mount } from '@link-foundation/ui-animation/backgrounds/shader';
84
99
  import { nebula } from '@link-foundation/ui-animation/backgrounds/nebula';
@@ -117,7 +132,10 @@ step is every 6 frames at 60 Hz and 13 at 120 Hz. Destination-out fading keeps
117
132
  the canvas transparent. Old heads are repainted without glow. About once per
118
133
  second an SVG alpha table clears values ≤9/255; a pixel pass covers engines
119
134
  without working SVG filters. Reduced motion paints a deterministic static field
120
- with alpha 0.2..0.8.
135
+ with alpha 0.2..0.8. Choose `calibration: 'batched'` to use 60 Hz until the
136
+ first complete window, then the upper median of each non-overlapping
137
+ 30-gap window. A pause discards partial samples and keeps the calibrated rate.
138
+ `createCadence('batched')` exposes the same quantizer for a host scheduler.
121
139
 
122
140
  ## Grid pattern and registration
123
141
 
@@ -125,7 +143,18 @@ with alpha 0.2..0.8.
125
143
  (`lines`, `dashed`, `crosses`, `dots`), `level` (0..4), `tint` (`line`, `accent`,
126
144
  `second-accent`, `custom`), `color`, `radialFade`, `period` (0..120 s, 0 still).
127
145
  Theme tints use `--color-line`, `--color-accent` and `--color-accent-2`.
146
+ Use `tokens: { line: '--host-line', alpha: '--host-alpha' }` to bind a live
147
+ theme color and an independent opacity multiplier. For raw RGB channel
148
+ tokens, use `tint: 'custom'` with `color: 'rgb(var(--host-line-rgb))'`.
128
149
 
129
150
  The CSS pattern is one extra cell tall. `onDrift(px)` receives the shared offset;
130
151
  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.
152
+ shifts by exactly one cell. Grid, beams and rain accept `originX` and
153
+ `originY` in CSS pixels. Supply `gridOffset(timeMs, cellSize, periodMs)` as the
154
+ grid's explicit `drift` to use a fixed host clock. Pass `drift: undefined`
155
+ to the grid to resume internally integrated drift. Rain and beams also accept
156
+ the host's `random(seed)` factory for repeatable fields and paths.
157
+
158
+ The [host integration example](../../../../examples/themes/host-integration/)
159
+ shows a host-drawn star reference alongside the mounted starfield, a saved
160
+ shader clock and one phase shared by independently mounted layers.
@@ -1,7 +1,12 @@
1
- import type { CommonOptions, LayerHandle } from './common.js';
2
- export interface BeamOptions extends CommonOptions {
1
+ import type {
2
+ CommonOptions,
3
+ LayerHandle,
4
+ GridCoordinates,
5
+ RandomSource,
6
+ } from './common.js';
7
+ export interface BeamOptions extends CommonOptions, GridCoordinates {
3
8
  seed?: number | string;
4
- cellSize?: number;
9
+ random?: RandomSource;
5
10
  style?: 'comet' | 'segment' | 'pulse' | 'scan';
6
11
  direction?: 'horizontal' | 'vertical' | 'both';
7
12
  bothSenses?: boolean;
@@ -13,7 +18,6 @@ export interface BeamOptions extends CommonOptions {
13
18
  glow?: number;
14
19
  pause?: number;
15
20
  snap?: boolean;
16
- drift?: number;
17
21
  }
18
22
  export function mount(
19
23
  canvas: HTMLCanvasElement,
@@ -1,5 +1,5 @@
1
1
  import { seededRandom } from '../random.js';
2
- import { mountLayer, changed, clamp, bounded } from './common.js';
2
+ import { mountLayer, changed, clamp, bounded, wrapGrid } from './common.js';
3
3
 
4
4
  const defaults = {
5
5
  seed: 224,
@@ -16,6 +16,9 @@ const defaults = {
16
16
  pause: 1,
17
17
  snap: true,
18
18
  drift: 0,
19
+ originX: 0,
20
+ originY: 0,
21
+ random: seededRandom,
19
22
  };
20
23
  function create(canvas) {
21
24
  const ctx = canvas.getContext('2d');
@@ -26,7 +29,7 @@ function create(canvas) {
26
29
  area,
27
30
  beams = [];
28
31
  function seed() {
29
- const random = seededRandom(o.seed);
32
+ const random = o.random(o.seed);
30
33
  beams = Array.from({ length: Math.round(clamp(o.count, 1, 40)) }, () => ({
31
34
  vertical:
32
35
  o.direction === 'vertical' ||
@@ -66,9 +69,12 @@ function create(canvas) {
66
69
  b.wait = o.pause;
67
70
  }
68
71
  const across = b.line * (b.vertical ? area.width : area.height);
72
+ const origin = b.vertical ? o.originX : o.originY;
69
73
  const line =
70
- (o.snap ? Math.round(across / o.cellSize) * o.cellSize : across) +
71
- (b.vertical ? 0 : o.drift);
74
+ (o.snap
75
+ ? Math.round(across / o.cellSize) * o.cellSize +
76
+ wrapGrid(origin, o.cellSize)
77
+ : across) + (b.vertical ? 0 : o.drift);
72
78
  const head = b.sense > 0 ? b.position * extent : (1 - b.position) * extent;
73
79
  ctx.save();
74
80
  if (b.vertical) {
@@ -108,6 +114,7 @@ function create(canvas) {
108
114
  'direction',
109
115
  'bothSenses',
110
116
  'seed',
117
+ 'random',
111
118
  'snap',
112
119
  ])
113
120
  ) {
@@ -5,6 +5,16 @@ export interface LayerHandle<Options = CommonOptions> {
5
5
  animate(on: boolean): void;
6
6
  dispose(): void;
7
7
  }
8
+ /** A factory for a repeatable stream, called when a layer lays out a scene. */
9
+ export type RandomSource = (seed: number | string) => () => number;
10
+ export interface GridCoordinates {
11
+ cellSize?: number;
12
+ /** Base grid intersection in CSS pixels, before downward drift. */
13
+ originX?: number;
14
+ originY?: number;
15
+ /** Downward phase in CSS pixels. Use gridOffset() to share a host clock. */
16
+ drift?: number;
17
+ }
8
18
  export interface CommonOptions {
9
19
  animate?: boolean;
10
20
  fps?: number;
@@ -13,6 +13,10 @@ export const bounded = (options, ranges) => ({
13
13
  ])
14
14
  ),
15
15
  });
16
+ export function wrapGrid(value, cellSize) {
17
+ const remainder = value % cellSize;
18
+ return remainder < 0 ? remainder + cellSize : remainder;
19
+ }
16
20
  export const radians = (degrees) => (Number(degrees) * Math.PI) / 180;
17
21
  export const noop = () => ({ update() {}, animate() {}, dispose() {} });
18
22
  export const changed = (a, b, keys) => keys.some((key) => a[key] !== b[key]);
@@ -1,6 +1,5 @@
1
- import type { CommonOptions, LayerHandle } from './common.js';
2
- export interface GridOptions extends CommonOptions {
3
- cellSize?: number;
1
+ import type { CommonOptions, LayerHandle, GridCoordinates } from './common.js';
2
+ export interface GridOptions extends CommonOptions, GridCoordinates {
4
3
  lineWidth?: number;
5
4
  markLength?: number;
6
5
  pattern?: 'lines' | 'dashed' | 'crosses' | 'dots';
@@ -8,9 +7,19 @@ export interface GridOptions extends CommonOptions {
8
7
  color?: string;
9
8
  radialFade?: boolean;
10
9
  period?: number;
10
+ /** Live CSS custom-property names for tint colors and a separate opacity multiplier. */
11
+ tokens?: Partial<
12
+ Record<'line' | 'accent' | 'second-accent' | 'custom' | 'alpha', string>
13
+ >;
11
14
  onDrift?: (px: number) => void;
12
15
  }
13
16
  export function mount(
14
17
  element: HTMLElement,
15
18
  options?: GridOptions
16
19
  ): LayerHandle<GridOptions>;
20
+ /** Return the phase in CSS pixels for a clock and period in milliseconds. */
21
+ export function gridOffset(
22
+ time: number,
23
+ cellSize: number,
24
+ period: number
25
+ ): number;
@@ -1,4 +1,4 @@
1
- import { mountLayer, changed, bounded } from './common.js';
1
+ import { mountLayer, changed, bounded, wrapGrid } from './common.js';
2
2
 
3
3
  const defaults = {
4
4
  cellSize: 64,
@@ -11,26 +11,24 @@ const defaults = {
11
11
  radialFade: false,
12
12
  period: 30,
13
13
  onDrift: undefined,
14
+ drift: undefined,
15
+ originX: 0,
16
+ originY: 0,
17
+ tokens: undefined,
14
18
  };
15
19
 
16
- function background(element, win, o) {
17
- const token = {
18
- line: '--color-line',
19
- accent: '--color-accent',
20
- 'second-accent': '--color-accent-2',
21
- }[o.tint];
22
- const color =
23
- (token && win.getComputedStyle?.(element).getPropertyValue(token).trim()) ||
24
- o.color;
25
- const escaped = color
26
- .replaceAll('&', '&amp;')
27
- .replaceAll('"', '&quot;')
28
- .replaceAll('<', '&lt;');
20
+ const defaultTokens = {
21
+ line: '--color-line',
22
+ accent: '--color-accent',
23
+ 'second-accent': '--color-accent-2',
24
+ };
25
+
26
+ function mask(o) {
29
27
  const cell = o.cellSize,
30
28
  mark = cell * o.markLength;
31
29
  let artwork;
32
30
  if (o.pattern === 'dots') {
33
- artwork = `<circle cx="${cell / 2}" cy="${cell / 2}" r="${o.lineWidth}" fill="${escaped}"/>`;
31
+ artwork = `<circle cx="${cell / 2}" cy="${cell / 2}" r="${o.lineWidth}" fill="white"/>`;
34
32
  } else {
35
33
  const center = cell / 2;
36
34
  let path = `M0 ${center}H${cell}M${center} 0V${cell}`;
@@ -39,13 +37,13 @@ function background(element, win, o) {
39
37
  }
40
38
  const dash =
41
39
  o.pattern === 'dashed' ? `stroke-dasharray="${mark} ${cell - mark}"` : '';
42
- artwork = `<path d="${path}" stroke="${escaped}" stroke-width="${o.lineWidth}" ${dash}/>`;
40
+ artwork = `<path d="${path}" stroke="white" stroke-width="${o.lineWidth}" ${dash}/>`;
43
41
  }
44
42
  // Original CSS image, offset by half a cell so marks land on grid lines.
45
43
  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${cell}" height="${cell}" viewBox="0 0 ${cell} ${cell}">${artwork}</svg>`;
46
44
  return `url("data:image/svg+xml,${encodeURIComponent(svg)}")`;
47
45
  }
48
- function create(element, win) {
46
+ function create(element) {
49
47
  let o,
50
48
  offset = 0,
51
49
  dirty = true;
@@ -58,6 +56,8 @@ function create(element, win) {
58
56
  }
59
57
  dirty = false;
60
58
  const cell = o.cellSize;
59
+ const colorToken = o.tokens?.[o.tint] ?? defaultTokens[o.tint];
60
+ const alphaToken = o.tokens?.alpha;
61
61
  Object.assign(element.style, {
62
62
  overflow: 'hidden',
63
63
  maskImage: o.radialFade
@@ -67,12 +67,15 @@ function create(element, win) {
67
67
  Object.assign(pattern.style, {
68
68
  position: 'absolute',
69
69
  inset: `-${cell}px 0 0`,
70
- backgroundImage: background(element, win, o),
71
- backgroundSize: `${cell}px ${cell}px`,
72
- backgroundPosition: `${-cell / 2}px ${-cell / 2}px`,
73
- backgroundRepeat: 'repeat',
70
+ backgroundColor: colorToken ? `var(${colorToken}, ${o.color})` : o.color,
71
+ maskImage: mask(o),
72
+ maskSize: `${cell}px ${cell}px`,
73
+ maskPosition: `${wrapGrid(o.originX, cell) - cell / 2}px ${wrapGrid(o.originY, cell) - cell / 2}px`,
74
+ maskRepeat: 'repeat',
74
75
  transform: `translateY(${offset}px)`,
75
- opacity: String(o.level / 4),
76
+ opacity: alphaToken
77
+ ? `calc(${o.level / 4} * var(${alphaToken}, 1))`
78
+ : String(o.level / 4),
76
79
  });
77
80
  }
78
81
  return {
@@ -95,9 +98,12 @@ function create(element, win) {
95
98
  'tint',
96
99
  'color',
97
100
  'radialFade',
101
+ 'originX',
102
+ 'originY',
103
+ 'tokens',
98
104
  ]);
99
105
  dirty ||= visual;
100
- return visual;
106
+ return visual || next.drift !== before.drift;
101
107
  },
102
108
  invalidate() {
103
109
  dirty = true;
@@ -105,10 +111,13 @@ function create(element, win) {
105
111
  resize() {},
106
112
  draw(dt, { still }) {
107
113
  const cell = o.cellSize;
108
- if (!still && o.period > 0) {
109
- offset += (dt * cell) / o.period;
114
+ if (Number.isFinite(o.drift)) {
115
+ offset = wrapGrid(o.drift, cell);
116
+ } else if (!still && o.period > 0) {
117
+ offset = wrapGrid(offset + (dt * cell) / o.period, cell);
118
+ } else {
119
+ offset = wrapGrid(offset, cell);
110
120
  }
111
- offset %= cell;
112
121
  paint();
113
122
  o.onDrift?.(offset);
114
123
  },
@@ -117,6 +126,11 @@ function create(element, win) {
117
126
  },
118
127
  };
119
128
  }
129
+ /** Convert a host clock in milliseconds to a one-cell phase. */
130
+ export function gridOffset(time, cellSize, period) {
131
+ return period > 0 ? (wrapGrid(time, period) / period) * cellSize : 0;
132
+ }
133
+
120
134
  /** Mount on a positioned div; other layers mount on canvases. */
121
135
  export const mount = (element, options = {}) =>
122
136
  mountLayer(element, options, create);
@@ -1,8 +1,15 @@
1
- import type { CommonOptions, LayerHandle } from './common.js';
2
- export interface RainOptions extends CommonOptions {
1
+ import type {
2
+ CommonOptions,
3
+ LayerHandle,
4
+ GridCoordinates,
5
+ RandomSource,
6
+ } from './common.js';
7
+ export interface RainOptions extends CommonOptions, GridCoordinates {
3
8
  seed?: number | string;
4
- cellSize?: number;
9
+ random?: RandomSource;
5
10
  step?: number;
11
+ /** Batched calibration only changes after 30 valid gaps, using the upper median. */
12
+ calibration?: 'rolling' | 'batched';
6
13
  columnSteps?: number;
7
14
  density?: number;
8
15
  restart?: number;
@@ -11,7 +18,6 @@ export interface RainOptions extends CommonOptions {
11
18
  padding?: number;
12
19
  color?: string;
13
20
  visible?: boolean;
14
- drift?: number;
15
21
  pick?: () => unknown;
16
22
  paint?: (
17
23
  ctx: CanvasRenderingContext2D,
@@ -26,7 +32,7 @@ export function mount(
26
32
  canvas: HTMLCanvasElement,
27
33
  options?: RainOptions
28
34
  ): LayerHandle<RainOptions>;
29
- export function createCadence(): {
35
+ export function createCadence(mode?: RainOptions['calibration']): {
30
36
  frame(gap: number): void;
31
37
  ready(step: number, fps: number): boolean;
32
38
  reset(): void;
@@ -1,5 +1,5 @@
1
1
  import { seededRandom } from '../random.js';
2
- import { mountLayer, changed, clamp, bounded } from './common.js';
2
+ import { mountLayer, changed, clamp, bounded, wrapGrid } from './common.js';
3
3
  import { alphaCleanup } from './rain-cleanup.js';
4
4
 
5
5
  const defaultPaint = (ctx, glyph, x, y, size) => {
@@ -21,33 +21,44 @@ const defaults = {
21
21
  drift: 0,
22
22
  paint: defaultPaint,
23
23
  pick: undefined,
24
+ random: seededRandom,
25
+ calibration: 'rolling',
26
+ originX: 0,
27
+ originY: 0,
24
28
  };
25
29
 
26
30
  /** Quantize to whole measured display frames; never take two steps in one frame. */
27
- export function createCadence() {
31
+ export function createCadence(mode = 'rolling') {
28
32
  const gaps = [];
33
+ let frameMs = 1000 / 60;
29
34
  let frames = 0;
35
+ const batched = mode === 'batched';
30
36
  return {
31
37
  frame(gap) {
32
- if (gap > 0 && gap < 100) {
33
- gaps.push(gap);
34
- if (gaps.length > 30) {
35
- gaps.shift();
36
- }
38
+ if (gap <= 0 || gap >= 100 || !Number.isFinite(gap)) {
39
+ return;
40
+ }
41
+ gaps.push(gap);
42
+ if (batched && gaps.length < 30) {
43
+ return;
44
+ }
45
+ if (gaps.length > 30) {
46
+ gaps.shift();
47
+ }
48
+ const sorted = gaps.toSorted((a, b) => a - b);
49
+ const middle = Math.floor(sorted.length / 2);
50
+ frameMs = sorted[middle];
51
+ if (batched) {
52
+ gaps.length = 0;
53
+ } else if (sorted.length % 2 === 0) {
54
+ frameMs = (frameMs + sorted[middle - 1]) / 2;
37
55
  }
38
56
  },
39
57
  ready(step, fps) {
40
- const sorted = [...gaps].sort((a, b) => a - b);
41
- const middle = Math.floor(sorted.length / 2);
42
- const median = sorted.length
43
- ? (sorted[middle] +
44
- sorted[Math.max(0, Math.ceil(sorted.length / 2) - 1)]) /
45
- 2
46
- : 1000 / 60;
47
58
  frames++;
48
59
  const count = Math.max(
49
60
  1,
50
- Math.round(Math.max(clamp(step, 20, 400), 1000 / fps) / median)
61
+ Math.round(Math.max(clamp(step, 20, 400), 1000 / fps) / frameMs)
51
62
  );
52
63
  if (frames < count) {
53
64
  return false;
@@ -57,25 +68,28 @@ export function createCadence() {
57
68
  },
58
69
  reset() {
59
70
  frames = 0;
71
+ if (batched) {
72
+ gaps.length = 0;
73
+ }
60
74
  },
61
75
  };
62
76
  }
63
77
 
64
- function shiftCanvas(canvas, ctx, dy) {
65
- if (!dy) {
78
+ function shiftCanvas(canvas, ctx, dx, dy) {
79
+ if (!dx && !dy) {
66
80
  return;
67
81
  }
68
82
  ctx.save();
69
83
  ctx.setTransform(1, 0, 0, 1, 0, 0);
70
84
  ctx.globalCompositeOperation = 'copy';
71
85
  ctx.globalAlpha = 1;
72
- ctx.drawImage(canvas, 0, dy);
86
+ ctx.drawImage(canvas, dx, dy);
73
87
  ctx.restore();
74
88
  }
75
89
 
76
90
  function stillField(ctx, area, columns, o, glyph) {
77
91
  ctx.clearRect(0, 0, area.width, area.height);
78
- const fieldRandom = seededRandom(o.seed);
92
+ const fieldRandom = o.random(o.seed);
79
93
  for (const column of columns) {
80
94
  if (!column.active) {
81
95
  continue;
@@ -103,18 +117,19 @@ function create(canvas) {
103
117
  return null;
104
118
  }
105
119
  const cleanup = alphaCleanup(canvas, ctx);
106
- const cadence = createCadence();
107
- let o,
120
+ let cadence,
121
+ o,
108
122
  area,
109
123
  columns = [],
110
124
  random,
111
125
  steps = 0,
112
126
  cleanupTime = 0,
113
- priorDrift = 0;
127
+ previousX = 0,
128
+ previousY = 0;
114
129
  const pick = () =>
115
130
  o.pick?.() ?? String.fromCharCode(0x30 + Math.floor(random() * 10));
116
131
  function seed() {
117
- random = seededRandom(o.seed);
132
+ random = o.random(o.seed);
118
133
  const spacing = clamp(o.cellSize, 32, 128) / 2;
119
134
  columns = Array.from(
120
135
  { length: Math.ceil(area.width / spacing) },
@@ -137,8 +152,8 @@ function create(canvas) {
137
152
  o.paint(
138
153
  ctx,
139
154
  column.glyph,
140
- column.x + padding,
141
- column.y + o.drift,
155
+ column.x + padding + wrapGrid(o.originX, spacing),
156
+ column.y + o.drift + wrapGrid(o.originY, spacing),
142
157
  Math.max(1, spacing - padding),
143
158
  glow
144
159
  );
@@ -146,9 +161,9 @@ function create(canvas) {
146
161
  }
147
162
  return {
148
163
  defaults,
149
- frame: cadence.frame,
164
+ frame: (gap) => cadence.frame(gap),
150
165
  cadence: (fps) => cadence.ready(o.step, fps),
151
- resetClock: cadence.reset,
166
+ resetClock: () => cadence.reset(),
152
167
  update(next, before) {
153
168
  o = bounded(next, {
154
169
  cellSize: [32, 128],
@@ -160,17 +175,19 @@ function create(canvas) {
160
175
  glow: [0, 40],
161
176
  padding: [0, 16],
162
177
  });
163
- if (area && changed(next, before, ['cellSize', 'seed'])) {
164
- seed();
178
+ if (!cadence || next.calibration !== before.calibration) {
179
+ cadence = createCadence(o.calibration);
165
180
  }
166
- if (area && next.density !== before.density) {
167
- const active = seededRandom(o.seed);
181
+ if (area && changed(next, before, ['cellSize', 'seed', 'random'])) {
182
+ seed();
183
+ } else if (area && next.density !== before.density) {
184
+ const active = o.random(o.seed);
168
185
  columns.forEach((c) => {
169
186
  c.active = active() < o.density;
170
187
  });
171
188
  }
172
189
  if (area && next.columnSteps !== before.columnSteps) {
173
- const speed = seededRandom(o.seed);
190
+ const speed = o.random(o.seed);
174
191
  columns.forEach((c) => {
175
192
  c.every = 1 + Math.floor(speed() * clamp(o.columnSteps, 1, 8));
176
193
  });
@@ -179,7 +196,10 @@ function create(canvas) {
179
196
  next,
180
197
  before,
181
198
  Object.keys(defaults).filter(
182
- (key) => !['step', 'columnSteps', 'restart', 'fade'].includes(key)
199
+ (key) =>
200
+ !['step', 'columnSteps', 'restart', 'fade', 'calibration'].includes(
201
+ key
202
+ )
183
203
  )
184
204
  );
185
205
  },
@@ -192,9 +212,14 @@ function create(canvas) {
192
212
  draw(dt, { still, frame }) {
193
213
  ctx.setTransform(area.ratio, 0, 0, area.ratio, 0, 0);
194
214
  // Round the absolute offset so subpixel deltas accumulate across frames.
195
- const drift = Math.round(o.drift * area.ratio);
196
- shiftCanvas(canvas, ctx, drift - priorDrift);
197
- priorDrift = drift;
215
+ const spacing = o.cellSize / 2;
216
+ const x = Math.round(wrapGrid(o.originX, spacing) * area.ratio);
217
+ const y = Math.round(
218
+ (o.drift + wrapGrid(o.originY, spacing)) * area.ratio
219
+ );
220
+ shiftCanvas(canvas, ctx, x - previousX, y - previousY);
221
+ previousX = x;
222
+ previousY = y;
198
223
  if (!o.visible) {
199
224
  return;
200
225
  }
@@ -1,12 +1,15 @@
1
- import type { CommonOptions, LayerHandle } from './common.js';
1
+ import type { CommonOptions, LayerHandle, RandomSource } from './common.js';
2
2
  export type Uniform = number | string | { degrees: number };
3
3
  export interface ShaderOptions extends CommonOptions {
4
4
  source: string;
5
5
  uniforms?: Record<string, Uniform>;
6
6
  /** Named independent clocks and their speeds. */
7
7
  times?: Record<string, number>;
8
- startTime?: number | 'random';
8
+ startTime?: number | 'random' | Record<string, number | 'random'>;
9
+ /** Host-owned clock values in seconds by uniform name. Update with a new map to seek. */
10
+ clock?: Record<string, number>;
9
11
  seed?: number | string;
12
+ random?: RandomSource;
10
13
  }
11
14
  export function mount(
12
15
  canvas: HTMLCanvasElement,
@@ -9,6 +9,8 @@ const defaults = {
9
9
  times: { time: 1 },
10
10
  startTime: 0,
11
11
  seed: 224,
12
+ random: seededRandom,
13
+ clock: undefined,
12
14
  };
13
15
  function compile(gl, type, source) {
14
16
  const shader = gl.createShader(type);
@@ -58,6 +60,12 @@ function upload(gl, location, value) {
58
60
  gl.uniform1f(location, radians(value.degrees));
59
61
  }
60
62
  }
63
+ function clockStart(value, name) {
64
+ if (value && typeof value === 'object') {
65
+ return Object.hasOwn(value, name) ? value[name] : 0;
66
+ }
67
+ return value ?? 0;
68
+ }
61
69
  function create(canvas, win, initial) {
62
70
  const gl = canvas.getContext('webgl', {
63
71
  alpha: false,
@@ -107,17 +115,29 @@ function create(canvas, win, initial) {
107
115
  o.onError?.(error);
108
116
  }
109
117
  }
118
+ let reset = false;
110
119
  for (const name of Object.keys(next.times)) {
111
- if (!clocks.has(name) || next.startTime !== before.startTime) {
120
+ const start = clockStart(next.startTime, name);
121
+ if (
122
+ !clocks.has(name) ||
123
+ start !== clockStart(before.startTime, name) ||
124
+ (start === 'random' && changed(next, before, ['seed', 'random']))
125
+ ) {
112
126
  clocks.set(
113
127
  name,
114
- next.startTime === 'random'
115
- ? seededRandom(`${next.seed}:${name}`)() * 1000
116
- : Number(next.startTime)
128
+ start === 'random'
129
+ ? next.random(`${next.seed}:${name}`)() * 1000
130
+ : start
117
131
  );
132
+ reset = true;
133
+ }
134
+ }
135
+ for (const name of clocks.keys()) {
136
+ if (!Object.hasOwn(next.times, name)) {
137
+ clocks.delete(name);
118
138
  }
119
139
  }
120
- return changed(next, before, ['source', 'uniforms', 'startTime']);
140
+ return reset || changed(next, before, ['source', 'uniforms', 'clock']);
121
141
  },
122
142
  resize(next) {
123
143
  area = next;
@@ -132,7 +152,10 @@ function create(canvas, win, initial) {
132
152
  gl.uniform2f(location('resolution'), canvas.width, canvas.height);
133
153
  gl.uniform1f(location('pixelRatio'), area.ratio);
134
154
  for (const [name, speed] of Object.entries(o.times)) {
135
- const time = clocks.get(name) + (still ? 0 : dt * speed);
155
+ const time =
156
+ o.clock && Object.hasOwn(o.clock, name)
157
+ ? o.clock[name]
158
+ : clocks.get(name) + (still ? 0 : dt * speed);
136
159
  clocks.set(name, time);
137
160
  gl.uniform1f(location(name), time);
138
161
  }
@@ -1,7 +1,39 @@
1
- import type { CommonOptions, LayerHandle } from './common.js';
1
+ import type { CommonOptions, LayerHandle, RandomSource } from './common.js';
2
+ export interface StarLayoutPoint {
3
+ /** Position relative to the CSS width and height. */
4
+ x: number;
5
+ y: number;
6
+ depth?: number;
7
+ phase?: number;
8
+ size?: number;
9
+ sprite?: number;
10
+ /** Optional authored scale, alpha and angle in degrees. */
11
+ scale?: number;
12
+ opacity?: number;
13
+ rotation?: number;
14
+ }
15
+ export interface StarSprite {
16
+ image: CanvasImageSource;
17
+ /** Destination size in CSS pixels before applying the star's scale. */
18
+ size: number;
19
+ }
2
20
  export interface StarfieldOptions extends CommonOptions {
3
21
  seed?: number | string;
22
+ random?: RandomSource;
4
23
  count?: number;
24
+ layout?: (input: {
25
+ count: number;
26
+ width: number;
27
+ height: number;
28
+ dpr: number;
29
+ random: () => number;
30
+ options: StarfieldOptions;
31
+ }) => readonly StarLayoutPoint[];
32
+ createSprites?: (input: {
33
+ canvas: HTMLCanvasElement;
34
+ dpr: number;
35
+ options: StarfieldOptions;
36
+ }) => readonly StarSprite[];
5
37
  shape?:
6
38
  | 'dot'
7
39
  | 'soft-dot'
@@ -22,12 +22,39 @@ const defaults = {
22
22
  speed: 20,
23
23
  streak: 0,
24
24
  blend: 'normal',
25
+ random: seededRandom,
26
+ layout: undefined,
27
+ createSprites: undefined,
25
28
  };
26
29
  const looks = ['shape', 'size', 'color', 'hueSpread', 'glow', 'glowColor'];
27
30
 
28
- function create(canvas, win) {
31
+ function placeStars(options, area) {
32
+ const random = options.random(options.seed);
33
+ const count = Math.min(
34
+ 6000,
35
+ Math.round(
36
+ (clamp(options.count, 0, 3000) * area.width * area.height) / (1920 * 1080)
37
+ )
38
+ );
39
+ if (options.layout) {
40
+ return options
41
+ .layout({ ...area, count, random, options })
42
+ .slice(0, 6000)
43
+ .map((star) => ({ depth: 1, phase: 0, size: 0, ...star }));
44
+ }
45
+ return Array.from({ length: count }, () => ({
46
+ x: random(),
47
+ y: random(),
48
+ depth: 0.2 + random() * 0.8,
49
+ phase: random() * Math.PI * 2,
50
+ size: random(),
51
+ hue: Math.floor(random() * 9),
52
+ }));
53
+ }
54
+
55
+ function create(canvas, win, initial) {
29
56
  const ctx = canvas.getContext('2d');
30
- if (!ctx || !win.Path2D) {
57
+ if (!ctx || (!win.Path2D && !initial.createSprites)) {
31
58
  return null;
32
59
  }
33
60
  let o,
@@ -37,27 +64,12 @@ function create(canvas, win) {
37
64
  dirty = true,
38
65
  twinkleClock = 0,
39
66
  rotationClock = 0;
40
- const seed = () => {
41
- const random = seededRandom(o.seed);
42
- const count = Math.min(
43
- 6000,
44
- Math.round(
45
- (clamp(o.count, 0, 3000) * area.width * area.height) / (1920 * 1080)
46
- )
47
- );
48
- stars = Array.from({ length: count }, () => ({
49
- x: random(),
50
- y: random(),
51
- depth: 0.2 + random() * 0.8,
52
- phase: random() * Math.PI * 2,
53
- size: random(),
54
- hue: Math.floor(random() * 9),
55
- }));
56
- };
57
67
  const rebuild = () => {
58
- sprites = Array.from({ length: 9 }, (_, i) =>
59
- sprite(canvas, win, o, area.dpr, (i / 4 - 1) * o.hueSpread)
60
- );
68
+ sprites = o.createSprites
69
+ ? o.createSprites({ canvas, options: o, dpr: area.dpr })
70
+ : Array.from({ length: 9 }, (_, i) =>
71
+ sprite(canvas, win, o, area.dpr, (i / 4 - 1) * o.hueSpread)
72
+ );
61
73
  dirty = false;
62
74
  };
63
75
  function advance(star, dt) {
@@ -102,9 +114,15 @@ function create(canvas, win) {
102
114
  speed: [0, 400],
103
115
  streak: [0, 20],
104
116
  });
105
- dirty ||= changed(next, before, looks);
106
- if (area && changed(next, before, ['count', 'seed'])) {
107
- seed();
117
+ dirty ||=
118
+ changed(next, before, looks) ||
119
+ next.createSprites !== before.createSprites ||
120
+ (o.createSprites && next.sizeSpread !== before.sizeSpread);
121
+ if (
122
+ area &&
123
+ changed(next, before, ['count', 'seed', 'random', 'layout'])
124
+ ) {
125
+ stars = placeStars(o, area);
108
126
  }
109
127
  return changed(
110
128
  next,
@@ -117,7 +135,7 @@ function create(canvas, win) {
117
135
  resize(next, old) {
118
136
  area = next;
119
137
  if (!old || changed(next, old, ['width', 'height'])) {
120
- seed();
138
+ stars = placeStars(o, area);
121
139
  }
122
140
  dirty ||= !old || next.dpr !== old.dpr;
123
141
  },
@@ -136,20 +154,24 @@ function create(canvas, win) {
136
154
  if (!still) {
137
155
  advance(star, dt);
138
156
  }
139
- const item = sprites[star.hue];
140
- const size = item.size * (1 - o.sizeSpread * star.size);
157
+ const item = sprites[star.sprite ?? star.hue] ?? sprites[0];
158
+ if (!item) {
159
+ continue;
160
+ }
161
+ const size = item.size * (star.scale ?? 1 - o.sizeSpread * star.size);
141
162
  ctx.globalAlpha = clamp(
142
- o.brightness *
143
- (1 -
144
- o.twinkleDepth *
145
- (0.5 +
146
- 0.5 * Math.sin(twinkleClock * Math.PI * 2 + star.phase))),
163
+ star.opacity ??
164
+ o.brightness *
165
+ (1 -
166
+ o.twinkleDepth *
167
+ (0.5 +
168
+ 0.5 * Math.sin(twinkleClock * Math.PI * 2 + star.phase))),
147
169
  0,
148
170
  1
149
171
  );
150
172
  ctx.save();
151
173
  ctx.translate(star.x * area.width, star.y * area.height);
152
- ctx.rotate(radians(o.rotation + rotationClock));
174
+ ctx.rotate(radians((star.rotation ?? o.rotation) + rotationClock));
153
175
  ctx.drawImage(
154
176
  item.image,
155
177
  -size / 2,