@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
package/LICENSE ADDED
@@ -0,0 +1,24 @@
1
+ This is free and unencumbered software released into the public domain.
2
+
3
+ Anyone is free to copy, modify, publish, use, compile, sell, or
4
+ distribute this software, either in source code form or as a compiled
5
+ binary, for any purpose, commercial or non-commercial, and by any
6
+ means.
7
+
8
+ In jurisdictions that recognize copyright laws, the author or authors
9
+ of this software dedicate any and all copyright interest in the
10
+ software to the public domain. We make this dedication for the benefit
11
+ of the public at large and to the detriment of our heirs and
12
+ successors. We intend this dedication to be an overt act of
13
+ relinquishment in perpetuity of all present and future rights to this
14
+ software under copyright law.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
19
+ IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
20
+ OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
21
+ ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
22
+ OTHER DEALINGS IN THE SOFTWARE.
23
+
24
+ For more information, please refer to <https://unlicense.org>
package/README.md CHANGED
@@ -1,3 +1,455 @@
1
- # Temporary Holding Version
1
+ # @link-foundation/ui-animation
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Animations of the associative UI framework, written in Links Notation. The
4
+ package has four parts:
5
+
6
+ 1. **a model** (`loadAnimations`): `animation` links with keyframe tracks,
7
+ easings, springs and procedural effects, `timeline` links with `at`,
8
+ `sequence`, `parallel` and `stagger`, and `(on STATE ...)` triggers;
9
+ 2. **a pure sampler** (`sample`, `sampleLayers`): the values of an animation
10
+ at a time, as a function of `(animation, t, seed)` only, so animations
11
+ can be scrubbed, recorded and tested;
12
+ 3. **a WAAPI compiler** (`toWaapi`): keyframes and options for
13
+ `element.animate()`;
14
+ 4. **a player** (`createPlayer`): it runs CSS properties on the Web
15
+ Animations API and effects and non-CSS properties on a frame loop
16
+ driven by an injectable clock, follows reduced motion and plays the
17
+ triggers of a [ui-store](../ui-store/README.md) document.
18
+
19
+ Safety is part of the model: `validateAnimation` reports fills that leave
20
+ `clip-path` or transforms on an element, photosensitive flashes (WCAG 2.3.1)
21
+ and movement without a reduced-motion variant.
22
+
23
+ Text is read only by the `parse` function of
24
+ [`@link-foundation/ui-core`](../ui-core/README.md), the official
25
+ `links-notation` parser. That is the only runtime dependency.
26
+
27
+ ```js
28
+ import {
29
+ loadAnimations,
30
+ validateAnimations,
31
+ createPlayer,
32
+ } from '@link-foundation/ui-animation';
33
+ import { mountDocument } from '@link-foundation/ui-dom';
34
+
35
+ const { store, handle } = mountDocument(app, documentText);
36
+ const model = loadAnimations(animationsText); // { animations, timelines, triggers, diagnostics }
37
+ validateAnimations(model, { resolveToken }); // [] when it is safe
38
+
39
+ const player = createPlayer(handle, { animations: model, resolveToken });
40
+ player.bindTriggers(store); // (on pressed ...) plays when `pressed` turns on
41
+ await player.play('intro').finished;
42
+ ```
43
+
44
+ The [example](../../examples/animation/index.html) plays an intro timeline
45
+ on a ui-dom document and has a reduced-motion toggle.
46
+
47
+ ## Model
48
+
49
+ ```lino
50
+ panel-enter: animation
51
+ duration 300ms
52
+ easing
53
+ cubic-bezier 0.2 0 0 1
54
+ fill backwards
55
+ track opacity
56
+ key 0 0
57
+ key 1 1
58
+ track translate
59
+ key 0 '0 8px'
60
+ key 1 '0 0'
61
+ reduced-motion
62
+ duration 0ms
63
+ bounce: animation
64
+ duration 600ms
65
+ easing
66
+ spring
67
+ stiffness 300
68
+ damping 20
69
+ mass 1
70
+ track scale
71
+ key 0 0.9
72
+ key 1 1
73
+ title-reveal: animation
74
+ target title
75
+ duration 900ms
76
+ effect decipher
77
+ seed 42
78
+ press-feedback: animation
79
+ target ok
80
+ duration
81
+ token motion.duration.short
82
+ easing standard
83
+ track scale
84
+ key 0 1
85
+ key 0.5 0.96
86
+ key 1 1
87
+ on pressed
88
+ intro: timeline
89
+ at 0ms
90
+ play panel-enter
91
+ target sidebar
92
+ at 120ms
93
+ stagger 50ms
94
+ play bounce
95
+ targets item-1 item-2 item-3
96
+ ```
97
+
98
+ Write one top-level link per line: Links Notation joins the links of one
99
+ line into a single link.
100
+
101
+ ### `animation`
102
+
103
+ | Part | Values | Default |
104
+ | ----------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------- |
105
+ | `(target ID)` | the store ID of the element it plays on | the `target` of `play` |
106
+ | `(duration TIME)` | `300ms`, `0.3s`, `(token motion.duration.short)` | the settle time of a spring, else 0 |
107
+ | `(delay TIME)` | as `duration` | `0ms` |
108
+ | `(iterations N)` | a number or `infinite` | `1` |
109
+ | `(direction D)` | `normal`, `reverse`, `alternate`, `alternate-reverse` | `normal` |
110
+ | `(fill F)` | `none`, `forwards`, `backwards`, `both`, `auto` | `none` |
111
+ | `(composite C)` | `replace`, `add`, `accumulate` | `replace` |
112
+ | `(easing E)` | see [Easings](#easings) | `linear` |
113
+ | `(track PROPERTY (key OFFSET VALUE [EASING])...)` | keyframes of one property; offsets 0–1, sorted | |
114
+ | `(effect NAME (seed S) (PARAM V)...)` | a registered procedural effect | |
115
+ | `(envelope bell\|sustain [(attack TIME)] [(release TIME)])` | the weight of an additive layer over its run | none |
116
+ | `(persist true)` | allows a final `clip-path` or transform to stay (see [Safety](#safety)) | `false` |
117
+ | `(on STATE [(play ID [(target ID)])])` | plays this animation (or `ID`) when its target enters `STATE` | |
118
+ | `(reduced-motion PART...)` | the parts that replace these under reduced motion | opacity tracks only, duration 0 |
119
+
120
+ **Values.** A key value is a number (`0.96`), a length or any CSS text with
121
+ units (`'0 8px'`, `'inset(0 100% 0 0)'`, `'45deg'`), a colour (`'#FF0000'`,
122
+ `(oklch ...)`, `(rgb ...)`, mixed in OKLCH) or `(token PATH)`. Texts with the
123
+ same shape are mixed number by number; other values switch at the middle.
124
+
125
+ **Properties.** Any CSS property runs on WAAPI. `text`, `label`, `value`,
126
+ `title`, `placeholder` and `progress` are not CSS: the player writes them
127
+ on every frame (`text` as the text content, `value` as the form value, the
128
+ others as attributes) and restores them when the animation no longer
129
+ applies (after its end without a fill).
130
+
131
+ **States.** A trigger state is `hover`, `focus`, `pressed` or `disabled`: a
132
+ store property of that name whose value is not `false`. An element can
133
+ also play animations on others: `(ok: button (on hover (play glow (target
134
+ help))))`.
135
+
136
+ ### Easings
137
+
138
+ - a name: `linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out`,
139
+ `step-start`, `step-end`, or a theme easing such as `standard` or
140
+ `emphasized`, read from the token `motion.easing.NAME` when the theme
141
+ has it;
142
+ - `(cubic-bezier x1 y1 x2 y2)`;
143
+ - `(steps n [start|end|jump-both|jump-none])`;
144
+ - `(spring (stiffness k) (damping c) (mass m))`: a closed-form damped
145
+ oscillator. Without `(duration ...)` the animation lasts until the spring
146
+ settles within 0.05% of its target; on WAAPI it runs as a CSS `linear()`
147
+ (`toCssLinear`).
148
+
149
+ A key may carry the easing of the segment that starts at it:
150
+ `(key 0 1 ease-out)`. Key offsets are literal fractions of the iteration duration, after delay and
151
+ playback direction. Animation easing is the default for each segment; a key's
152
+ explicit easing overrides it for the segment starting there. With no easing,
153
+ interpolation is linear. Thus the unchanged `press-feedback` sample reaches
154
+ scale `0.96` at 50% even with `easing standard`. See the normative
155
+ [timing contract](../../docs/spec/animation-timing.md) resolving #52 and #57.
156
+ Procedural effects have no key segments and retain whole-iteration easing.
157
+
158
+ ### `timeline`
159
+
160
+ ```
161
+ (NAME: timeline ITEM...)
162
+ ITEM = (play ID [(target ID)] [(targets ID...)])
163
+ | (at TIME ITEM...) starts its items TIME after its parent
164
+ | (sequence ITEM...) starts each item when the one before ends
165
+ | (parallel ITEM...) starts its items together
166
+ | (stagger STEP ITEM... [(targets ID...)])
167
+ the i-th target (or item) starts i * STEP later
168
+ ```
169
+
170
+ `(play ID)` can play another timeline. A timeline that plays itself is a
171
+ `timeline-cycle` diagnostic. `flattenTimeline(model, id)` returns the flat
172
+ schedule `[{ start, id, target }]`.
173
+
174
+ ### Diagnostics
175
+
176
+ `loadAnimations(text).diagnostics` and the validators use the ui-core shape
177
+ `{ code, severity, message, at }`:
178
+
179
+ | Code | Severity | When |
180
+ | ------------------------ | -------- | ------------------------------------------------------------------------------------- |
181
+ | `anonymous-animation` | warning | an `animation` or `timeline` has no id |
182
+ | `unknown-sublink` | warning | a part the model does not know |
183
+ | `invalid-value` | error | a value of the wrong type (`(duration fast)`) |
184
+ | `unknown-easing` | error | an easing that is not a name, bezier, steps or spring (a warning for an unknown name) |
185
+ | `empty-track` | error | a track without keys |
186
+ | `key-offset-range` | error | a key offset outside 0–1 |
187
+ | `key-offset-order` | error | key offsets that are not sorted |
188
+ | `unknown-effect` | warning | an effect that is not registered |
189
+ | `unknown-state` | warning | `(on STATE)` with a state that is not one of the four |
190
+ | `unknown-animation` | error | `play` of an id that is not an animation or timeline |
191
+ | `timeline-cycle` | error | a timeline that plays itself |
192
+ | `persistent-fill` | error | see [Safety](#safety) |
193
+ | `flash` | error | see [Safety](#safety) |
194
+ | `missing-reduced-motion` | warning | see [Safety](#safety) |
195
+
196
+ ## Safety
197
+
198
+ `validateAnimation(animation, { resolveToken })` and
199
+ `validateAnimations(model, options)` check three rules. They come from
200
+ regressions found in [immortality](https://github.com/konard/immortality/tree/main/docs/case-studies/issue-7).
201
+
202
+ - **Fill (`persistent-fill`, error).** `(fill both)` or `(fill forwards)` on
203
+ a `clip-path`, `transform`, `translate`, `scale` or `rotate` track keeps
204
+ the final value on the element after the animation ends, which clipped
205
+ and shifted panels. Use `(fill none)` or `(fill backwards)`, or write
206
+ `(persist true)` when the end state must stay.
207
+ - **Flash (`flash`, error).** WCAG 2.3.1 Three Flashes or Below Threshold.
208
+ `opacity`, `background-color` and `color` tracks are sampled at 60 Hz. A
209
+ change is a swing of relative luminance of at least 0.1 whose darker side
210
+ is below 0.8 (opacity is taken as the luminance of a white layer over
211
+ black, the worst case), and a flash is a pair of opposing changes. More
212
+ than 3 flashes in any one-second window is an error: an 8 Hz
213
+ `(steps 1)` opacity flicker fails, a 0.5 Hz breathing glow passes.
214
+ - **Reduced motion (`missing-reduced-motion`, warning).** A `translate`,
215
+ `scale`, `rotate` or `transform` track that runs for more than 0 ms
216
+ without a `(reduced-motion ...)` block. Under reduced motion such an
217
+ animation keeps only its opacity tracks, with duration 0.
218
+
219
+ The player follows reduced motion with `defaultMotion(element)`: it is
220
+ `reduced` when the closest `[data-motion]` ancestor says `reduced`, or when
221
+ the user agent prefers reduced motion. It then plays the
222
+ `(reduced-motion ...)` variant (`reducedMotionVariant`). Timeline `at`
223
+ offsets stay as written.
224
+
225
+ Randomness comes only from `seededRandom(seed)`: the package never calls
226
+ the global random source, so every frame is reproducible.
227
+
228
+ ## GSAP is not used
229
+
230
+ This package uses the Web Animations API and its own sampler. **GSAP must
231
+ never be added**, not even as an optional or development dependency: its
232
+ [standard licence](https://gsap.com/community/standard-license/) forbids
233
+ its use in tools that compete with its no-code animation products, which
234
+ a Links Notation animation editor is. `npm ls gsap` must stay empty (see
235
+ [existing solutions](../../docs/case-studies/issue-1/research/existing-solutions.md)).
236
+ Motion (MIT) may come later as an optional adapter.
237
+
238
+ ## API
239
+
240
+ ### Model
241
+
242
+ - `loadAnimations(text)` → `{ animations: Map, timelines: Map, triggers, diagnostics }`.
243
+ - `ANIMATION_STATES`, `ANIMATION_DEFAULTS`.
244
+
245
+ ### Sampling
246
+
247
+ - `sample(animation, tMs, { resolveToken, seed, input })` → `{ scale: 0.96, … }`:
248
+ CSS values as numbers or strings, effect output under its property. Pure:
249
+ the same arguments always give the same values.
250
+ - `sampleTyped(animation, tMs, options)` → `{ active, values, effects }` with
251
+ typed values.
252
+ - `sampleLayers(layers, tMs, options)`: sums `(composite add)` and
253
+ `(composite accumulate)` layers onto the `replace` layers below them, each
254
+ weighted by its envelope (`bell` is sin²(πp); `sustain` rises over its
255
+ attack, holds and falls over its release, 20% of the run each by
256
+ default), so nothing snaps. A layer is an animation or
257
+ `{ animation, start, seed, input }`.
258
+ - `envelopeWeight(envelope, progress, duration)`.
259
+
260
+ ### Easing
261
+
262
+ `linear`, `cubicBezier(x1, y1, x2, y2)`, `steps(n, position)`,
263
+ `spring({ stiffness, damping, mass })` → `{ at(tMs), settleTime }`,
264
+ `springEasing(spring)`, `toCssLinear(fn, samples = 40)`,
265
+ `easingFunction(easing, resolveToken)`, `easingCss(easing, resolveToken)`,
266
+ `NAMED_EASINGS`, `SPRING_TOLERANCE`.
267
+
268
+ ### Effects
269
+
270
+ - `registerEffect(name, fn, { property = 'text' })`, where `fn` is a pure
271
+ `(input, progress, seed, params) => output`; `getEffect(name)`,
272
+ `effectNames()`.
273
+ - `decipher(input, progress, seed)`: the text appears from random glyphs,
274
+ one character at a time in a seeded order. It is ported from
275
+ [immortality `textEffects.ts`](https://github.com/konard/immortality/blob/main/app/src/textEffects.ts)
276
+ (Unlicense).
277
+ - `seededRandom(seed)` (mulberry32), `seedNumber`, `hashString`, `mix`.
278
+
279
+ ### WAAPI
280
+
281
+ `toWaapi(animation, { resolveToken })` → `{ keyframes, options }`. For the
282
+ sample `press-feedback` with the sample tokens:
283
+
284
+ ```js
285
+ ({
286
+ keyframes: [
287
+ { offset: 0, easing: 'cubic-bezier(0.2, 0, 0, 1)', scale: '1' },
288
+ { offset: 0.5, easing: 'cubic-bezier(0.2, 0, 0, 1)', scale: '0.96' },
289
+ { offset: 1, easing: 'cubic-bezier(0.2, 0, 0, 1)', scale: '1' },
290
+ ],
291
+ options: {
292
+ duration: 150,
293
+ easing: 'linear',
294
+ fill: 'none',
295
+ composite: 'replace',
296
+ },
297
+ });
298
+ ```
299
+
300
+ Only CSS tracks become keyframes (`isCssProperty`, `NON_CSS_PROPERTIES`).
301
+
302
+ ### Player
303
+
304
+ ```js
305
+ const player = createPlayer(handle, {
306
+ animations, // LiNo text or a loaded model
307
+ resolveToken, // tokenResolver(resolveTokens(sets, 'material3'))
308
+ clock, // default: requestAnimationFrame and performance.now()
309
+ motion, // 'full' | 'reduced' | (element) => ...; default: defaultMotion
310
+ animate, // default: (element, keyframes, options) => element.animate(...)
311
+ seed, // the seed of effects without (seed ...)
312
+ });
313
+
314
+ const control = player.play('intro', { target, seed, input });
315
+ control.seek(75); // every run at 75 ms, paused
316
+ control.pause();
317
+ control.play();
318
+ control.cancel(); // restores the values from before and rejects `finished`
319
+ await control.finished;
320
+
321
+ const unsubscribe = player.bindTriggers(store);
322
+ ```
323
+
324
+ `handle` is a ui-dom handle (`nodeFor(id)`), a function of the id, or
325
+ `null`. `createManualClock()` gives a clock that only moves on
326
+ `advance(ms)`, so tests are deterministic; `systemClock()` is the default.
327
+ `triggersFor(model, store, id, state)` lists what plays when an element
328
+ enters a state.
329
+
330
+ ## Tests
331
+
332
+ ```sh
333
+ node --test packages/ui-animation/tests/*.test.js
334
+ npx playwright test tests/e2e/animation.spec.js --project=chromium
335
+ ```
336
+
337
+ The Playwright spec checks that `panel-enter` leaves the computed
338
+ `translate` and `clip-path` of the panel as they were before it, that the
339
+ intro timeline runs with its offsets and stagger, the reduced-motion
340
+ toggle, the `pressed` trigger, and the accessibility of the example.
341
+
342
+ ## License
343
+
344
+ [Unlicense](LICENSE) (public domain).
345
+
346
+ ## Recording format
347
+
348
+ The recorder stores the clock, inputs, store operations and animation starts,
349
+ not pixels. The initial `snapshot` is the store's LiNo operation log, inserting
350
+ all roots with their stable IDs and exact property lists. `set` is the readable
351
+ form of `setProp`; structural events use the merged store's operation syntax.
352
+ Other updates (`removeProp`, positional edits, duplicate properties and rename)
353
+ use `set` with an `operation` child carrying the original operation. No store
354
+ methods are patched and no fake snapshot/restore API is required.
355
+
356
+ ```js
357
+ import {
358
+ createRecorder,
359
+ replay,
360
+ stateAt,
361
+ animationsAt,
362
+ verifyReplay,
363
+ toPlaywright,
364
+ } from '@link-foundation/ui-animation';
365
+
366
+ const recorder = createRecorder({ store, player, root, handle, seed: 42 });
367
+ recorder.start();
368
+ recorder.mark('saved once');
369
+ const text = recorder.stop(); // detaches store, player and DOM listeners
370
+ const playback = replay(text, { store, player });
371
+ playback.seek(990);
372
+ playback.seek(0); // restores the initial snapshot, then applies due diffs
373
+ await playback.play();
374
+ const spec = toPlaywright(text, { url: '/examples/animation/' });
375
+ ```
376
+
377
+ ```lino
378
+ session-7: recording
379
+ started '2026-11-01T12:00:00Z'
380
+ seed 42
381
+ viewport 1280 800
382
+ document app
383
+ redacted true
384
+ event 0ms
385
+ set ok label OK
386
+ event 840ms
387
+ input pointer down ok
388
+ at 12 8
389
+ event 841ms
390
+ play press-feedback
391
+ target ok
392
+ event 990ms
393
+ set ok label Saved
394
+ ```
395
+
396
+ `parseRecording` accepts the official parser's nested and parenthesized forms;
397
+ `serializeRecording` writes the canonical nested form and preserves header and
398
+ event order. Event times are nonnegative integer milliseconds relative to
399
+ `start()`, with file order breaking ties. `started` is the wall-clock origin;
400
+ set `started` explicitly alongside an injected monotonic `clock` for fixtures.
401
+ Viewport and document ID are inferred from the root, or supplied explicitly.
402
+ `stateAt(text, ms)` returns a pure LiNo snapshot. `animationsAt(text, ms)` lists
403
+ uncancelled plays with local time and seed; pass `{ model, resolveToken }` to
404
+ filter completed animations and timelines before sampling them.
405
+
406
+ DOM listeners are passive and capture-phase. The render handle maps targets to
407
+ stable IDs, and pointer coordinates are relative to the target box. Pointer
408
+ moves retain at most one event per 1/60-second bucket for the session. Adjacent
409
+ text edits to the same field merge into the final value; intervening diffs or
410
+ other events preserve causal order. Password and `(sensitive true)` values are
411
+ redacted as `***` in the initial snapshot, insertions, updates and input events
412
+ by default. `redact: false` explicitly opts out. A DOM password target is also
413
+ remembered for subsequent store updates. `maxEvents` defaults to 100,000;
414
+ overflow retains the latest events in a ring and adds `truncated true`. Such
415
+ recordings can be inspected, but replay, verification and export reject them
416
+ because their missing prefix cannot be reproduced faithfully.
417
+
418
+ The shared `createManualClock()` runs timers at their exact due times, preserving
419
+ insertion order for ties. `advance(ms)` drives replay and player frames without
420
+ real time. `replay` applies recorded diffs and seeded animations; it does not
421
+ redispatch inputs. `pause()` resolves the pending `play()` call, and `seek()`
422
+ pauses playback. Store-triggered animations ignore operations with origin
423
+ `replay`, so recorded play events are not fired twice.
424
+
425
+ `verifyReplay(text, { createApp })` builds a fresh app with `createApp(seed,
426
+ clock)`. Return `{ store, dispatchInput(event), dispose?() }`: the verifier
427
+ restores the initial snapshot, dispatches only recorded inputs at their recorded
428
+ times, then compares resulting store diffs (including timestamps and order).
429
+ The injected clock must drive the app's timers too. The asynchronous result
430
+ contains `ok` and `{ time, expected, actual }` mismatches. Redacted recordings
431
+ can only verify handlers whose observable output is independent of the removed
432
+ secret values; a mismatch is reported rather than assuming those values.
433
+
434
+ Keyboard events use Playwright’s native keyboard API, including default button
435
+ activation. Text events skip a fill when the preceding key already produced the
436
+ recorded value, avoiding duplicate input notifications. Redacted keys remain
437
+ synthetic because their original character is unavailable.
438
+
439
+ `toPlaywright(text, { url })` exports a Playwright spec with a controlled clock,
440
+ viewport, stable `data-link-id` selectors, pointer/key/wheel/text/focus inputs,
441
+ property assertions and named `test.step` markers. DOM properties such as labels
442
+ and values are asserted directly. For store-only properties such as `pressed`, the page
443
+ exposes `window.uiRecordingState(id, name)` returning the property's raw values
444
+ (the animation example demonstrates the hook). The exported test includes no
445
+ runtime recorder dependency. Redacted text remains `***`; it cannot reconstruct
446
+ secrets. No rrweb code or dependency ships in this package.
447
+
448
+ Run the example at `/examples/animation/`: Record, interact with OK, Stop, then
449
+ Replay or move the labelled time scrubber. The `<pre>` shows the sharable LiNo.
450
+
451
+ ## Background layers
452
+
453
+ Independent decorative canvas, WebGL and CSS entry points are documented in
454
+ [backgrounds](src/backgrounds/README.md), with a runnable all-layer example,
455
+ original nebula preset, host glyph hooks and reduced-motion/CSS fallbacks.
package/package.json CHANGED
@@ -1,6 +1,79 @@
1
1
  {
2
2
  "name": "@link-foundation/ui-animation",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.0.0",
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
+ "type": "module",
6
+ "exports": {
7
+ ".": {
8
+ "types": "./src/index.d.ts",
9
+ "default": "./src/index.js"
10
+ },
11
+ "./backgrounds/starfield": {
12
+ "types": "./src/backgrounds/starfield.d.ts",
13
+ "default": "./src/backgrounds/starfield.js"
14
+ },
15
+ "./backgrounds/shader": {
16
+ "types": "./src/backgrounds/shader.d.ts",
17
+ "default": "./src/backgrounds/shader.js"
18
+ },
19
+ "./backgrounds/nebula": {
20
+ "types": "./src/backgrounds/nebula.d.ts",
21
+ "default": "./src/backgrounds/nebula.js"
22
+ },
23
+ "./backgrounds/beams": {
24
+ "types": "./src/backgrounds/beams.d.ts",
25
+ "default": "./src/backgrounds/beams.js"
26
+ },
27
+ "./backgrounds/rain": {
28
+ "types": "./src/backgrounds/rain.d.ts",
29
+ "default": "./src/backgrounds/rain.js"
30
+ },
31
+ "./backgrounds/grid": {
32
+ "types": "./src/backgrounds/grid.d.ts",
33
+ "default": "./src/backgrounds/grid.js"
34
+ }
35
+ },
36
+ "types": "./src/index.d.ts",
37
+ "files": [
38
+ "src/",
39
+ "README.md",
40
+ "LICENSE"
41
+ ],
42
+ "keywords": [
43
+ "ui",
44
+ "links-notation",
45
+ "animation",
46
+ "waapi",
47
+ "easing",
48
+ "spring",
49
+ "timeline",
50
+ "reduced-motion"
51
+ ],
52
+ "license": "Unlicense",
53
+ "repository": {
54
+ "type": "git",
55
+ "url": "git+https://github.com/link-foundation/ui.git",
56
+ "directory": "packages/ui-animation"
57
+ },
58
+ "homepage": "https://github.com/link-foundation/ui/tree/main/packages/ui-animation#readme",
59
+ "bugs": {
60
+ "url": "https://github.com/link-foundation/ui/issues"
61
+ },
62
+ "engines": {
63
+ "node": ">=20"
64
+ },
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"
69
+ },
70
+ "devDependencies": {
71
+ "@link-foundation/ui-tokens": "^0.0.0",
72
+ "esbuild": "0.27.0",
73
+ "jsdom": "^30.1.3",
74
+ "test-anywhere": "^0.8.48"
75
+ },
76
+ "publishConfig": {
77
+ "access": "public"
78
+ }
79
+ }