@link-foundation/ui-themes 0.0.0-stage → 0.1.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 (110) hide show
  1. package/LICENSE +24 -0
  2. package/README.md +121 -2
  3. package/package.json +52 -4
  4. package/src/classic/catalog.js +193 -0
  5. package/src/classic/effect-governor.js +199 -0
  6. package/src/classic/effect-quality.js +76 -0
  7. package/src/classic/frame-color.js +27 -0
  8. package/src/classic/frame-css-controls.js +65 -0
  9. package/src/classic/frame-css-corners.js +138 -0
  10. package/src/classic/frame-css-edge-geometry.js +74 -0
  11. package/src/classic/frame-css-edges.js +99 -0
  12. package/src/classic/frame-css-enums.js +65 -0
  13. package/src/classic/frame-css-geometry.js +133 -0
  14. package/src/classic/frame-css-modes.js +45 -0
  15. package/src/classic/frame-css-states.js +85 -0
  16. package/src/classic/frame-css-values.js +156 -0
  17. package/src/classic/frame-css.js +232 -0
  18. package/src/classic/frame-geometry.js +189 -0
  19. package/src/classic/frame-schema.js +328 -0
  20. package/src/classic/frame-vocabulary.js +10 -0
  21. package/src/classic/frames.d.ts +143 -0
  22. package/src/classic/frames.js +77 -0
  23. package/src/classic/material-visibility.js +94 -0
  24. package/src/classic/materials.d.ts +133 -0
  25. package/src/classic/materials.js +139 -0
  26. package/src/classic/optical-css.js +47 -0
  27. package/src/classic/optics.js +107 -0
  28. package/src/classic/refraction.js +145 -0
  29. package/src/fluent2/brand-aliases.js +157 -0
  30. package/src/fluent2/brand.js +84 -0
  31. package/src/fluent2/names.js +31 -0
  32. package/src/index.d.ts +54 -0
  33. package/src/index.js +79 -0
  34. package/src/mapping.js +135 -0
  35. package/src/material3/mapping.js +18 -0
  36. package/src/material3/mui.js +128 -0
  37. package/src/material3/seed.js +144 -0
  38. package/themes/base/theme.lino +35 -0
  39. package/themes/classic/README.md +90 -0
  40. package/themes/classic/deepcase/2025.lino +156 -0
  41. package/themes/classic/deepcase/classic.lino +86 -0
  42. package/themes/classic/deepcase/dark.lino +87 -0
  43. package/themes/classic/deepcase/deepcase-0.1.lino +63 -0
  44. package/themes/classic/deepcase/handler-windows.lino +22 -0
  45. package/themes/classic/deepcase/landing.lino +60 -0
  46. package/themes/classic/deepcase/perception.lino +88 -0
  47. package/themes/classic/formal-ai/chat-bubbles.lino +40 -0
  48. package/themes/classic/formal-ai/chat-cards.lino +40 -0
  49. package/themes/classic/formal-ai/chat-compact.lino +40 -0
  50. package/themes/classic/formal-ai/composer.lino +132 -0
  51. package/themes/classic/formal-ai/fa-contrast.lino +79 -0
  52. package/themes/classic/formal-ai/fa-flat.lino +79 -0
  53. package/themes/classic/formal-ai/fa-glass.lino +79 -0
  54. package/themes/classic/formal-ai/fa-material.lino +79 -0
  55. package/themes/classic/immortality/arwes.lino +59 -0
  56. package/themes/classic/immortality/palettes.lino +968 -0
  57. package/themes/classic/immortality/poseidon.lino +59 -0
  58. package/themes/classic/immortality/quiet.lino +59 -0
  59. package/themes/classic/konard/futuristic.lino +89 -0
  60. package/themes/classic/konard/glass.lino +89 -0
  61. package/themes/classic/konard/liquid.lino +89 -0
  62. package/themes/classic/meta-sovereign/chat-signal.lino +68 -0
  63. package/themes/classic/meta-sovereign/chat-t3.lino +68 -0
  64. package/themes/classic/meta-sovereign/chat-telegram.lino +74 -0
  65. package/themes/classic/meta-sovereign/chat-whatsapp.lino +68 -0
  66. package/themes/fluent2/LICENSE.txt +15 -0
  67. package/themes/fluent2/brand-aliases.lino +101 -0
  68. package/themes/fluent2/colors-dark.lino +1124 -0
  69. package/themes/fluent2/colors-high-contrast.lino +1109 -0
  70. package/themes/fluent2/colors.lino +1489 -0
  71. package/themes/fluent2/fluent-mapping.lino +120 -0
  72. package/themes/fluent2/motion-dark.lino +62 -0
  73. package/themes/fluent2/motion-high-contrast.lino +62 -0
  74. package/themes/fluent2/motion.lino +70 -0
  75. package/themes/fluent2/shadow-dark.lino +50 -0
  76. package/themes/fluent2/shadow-high-contrast.lino +50 -0
  77. package/themes/fluent2/shadow.lino +49 -0
  78. package/themes/fluent2/shape-dark.lino +47 -0
  79. package/themes/fluent2/shape-high-contrast.lino +47 -0
  80. package/themes/fluent2/shape.lino +46 -0
  81. package/themes/fluent2/spacing-dark.lino +68 -0
  82. package/themes/fluent2/spacing-high-contrast.lino +68 -0
  83. package/themes/fluent2/spacing.lino +67 -0
  84. package/themes/fluent2/styles.lino +511 -0
  85. package/themes/fluent2/templates.lino +60 -0
  86. package/themes/fluent2/theme.lino +31 -0
  87. package/themes/fluent2/type-dark.lino +83 -0
  88. package/themes/fluent2/type-high-contrast.lino +83 -0
  89. package/themes/fluent2/type.lino +82 -0
  90. package/themes/hig/colors.lino +54 -0
  91. package/themes/hig/materials.lino +7 -0
  92. package/themes/hig/motion.lino +13 -0
  93. package/themes/hig/shape.lino +5 -0
  94. package/themes/hig/spacing.lino +11 -0
  95. package/themes/hig/styles.lino +143 -0
  96. package/themes/hig/swiftui-mapping.lino +80 -0
  97. package/themes/hig/templates.lino +36 -0
  98. package/themes/hig/theme.lino +3 -0
  99. package/themes/hig/type.lino +26 -0
  100. package/themes/hig-ios/theme.lino +5 -0
  101. package/themes/hig-macos/theme.lino +5 -0
  102. package/themes/material3/colors.lino +320 -0
  103. package/themes/material3/elevation.lino +110 -0
  104. package/themes/material3/motion.lino +102 -0
  105. package/themes/material3/mui-mapping.lino +216 -0
  106. package/themes/material3/shape.lino +16 -0
  107. package/themes/material3/styles.lino +498 -0
  108. package/themes/material3/templates.lino +55 -0
  109. package/themes/material3/theme.lino +7 -0
  110. package/themes/material3/type.lino +336 -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,122 @@
1
- # Temporary Holding Version
1
+ # @link-foundation/ui-themes
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
+ Theme packages written in Links Notation. The collection contains `base`, `material3`, `fluent2`, `hig`, `hig-ios` and `hig-macos`, with light, dark, high contrast and reduced motion tokens, contrast
4
+ pairs, scoped styles and a button part template.
5
+
6
+ ```js
7
+ import { listThemes, loadTheme } from '@link-foundation/ui-themes';
8
+ import { compileThemeCss } from '@link-foundation/ui-tokens/themes';
9
+
10
+ listThemes(); // base, material3, fluent2, hig, hig-ios, hig-macos and the classic collection
11
+ const base = await loadTheme('base');
12
+ const css = compileThemeCss(base);
13
+ ```
14
+
15
+ `loadTheme(id)` asynchronously reads the shipped `.lino` file in Node or
16
+ fetches it relative to this module in the browser. Unknown IDs reject with a
17
+ `RangeError`. No build step or separate dark stylesheet is needed.
18
+
19
+ Pass `{ themes: [base] }` to `mountDocument` from `@link-foundation/ui-dom`.
20
+ The native button from `@link-foundation/ui-components/controls` consumes the
21
+ template at mount time. See [the theme contract](../../docs/spec/themes.md)
22
+ and [the runnable example](../../examples/themes/README.md).
23
+
24
+ The [classic collection](themes/classic/README.md) ships 38 DeepCase, konard,
25
+ immortality, formal-ai and meta-sovereign themes. Chat and composer packs define
26
+ only their own axis, so colours inherit from the enclosing skin. Open the
27
+ [classic gallery](../../examples/themes/classic.html) for all five families.
28
+
29
+ ```js
30
+ import { frameStyle } from '@link-foundation/ui-themes/classic/frames';
31
+ const frame = frameStyle({ corner: 'cut', line: 'accent', size: 12 });
32
+ // frame is nested style-rule LiNo; pass it to ui-style.readStyles.
33
+ ```
34
+
35
+ [Fluent 2](../../docs/themes/fluent2.md) supplies Microsoft token aliases,
36
+ a 16-stop brand-ramp helper and a Fluent UI React v9 migration mapping. Its
37
+ MIT token notice ships in `themes/fluent2/LICENSE.txt`; Fluent is a development
38
+ dependency only.
39
+
40
+ Material 3 includes generated light, dark and high-contrast color schemes,
41
+ type, shape, elevation, motion and state tokens, and control styles/templates.
42
+ See [the Material 3 API and generated MUI mapping](../../docs/themes/material3.md)
43
+ and [the gallery](../../examples/themes/material3.html).
44
+
45
+ `materialThemeFromSeed` uses `@material/material-color-utilities` **0.3.0**
46
+ (Apache-2.0, Google LLC), pinned because 0.4.0 has broken published ESM imports
47
+ ([upstream #195](https://github.com/material-foundation/material-color-utilities/issues/195)).
48
+ Its [source and license](https://github.com/material-foundation/material-color-utilities)
49
+ remain upstream; no Material Web, MUI, fonts or icons are bundled.
50
+ Regenerate colors with `node packages/ui-themes/scripts/generate-material3.mjs`.
51
+ The HIG themes are guided by the Apple Human Interface Guidelines and are not affiliated with or endorsed by Apple. They use system font names and our own values, with no bundled Apple assets. See [HIG tokens, controls and SwiftUI mapping](../../docs/themes/hig.md) and the [gallery](../../examples/themes/hig.html).
52
+
53
+ ## Independent frames and optical materials
54
+
55
+ `readFrames`, `resolveFrame` and `frameGeometry` from `./classic/frames` support
56
+ independent corners, edges, state overrides and explicit level inheritance.
57
+ `./classic/materials` supplies material parameters, appearance presets and a
58
+ shared opt-in animation/sound governor. See the
59
+ [frame and material contract](../../docs/spec/frames.md) and the
60
+ [original optical example](../../examples/themes/optical-frames/README.md).
61
+
62
+ ### Adaptive effect governor
63
+
64
+ `createEffectGovernor` from `@link-foundation/ui-themes/classic/materials`
65
+ shares a frame scheduler across host artwork effects. Existing
66
+ `draw(time, state)` callbacks remain supported; `time` is the animation-frame
67
+ clock in milliseconds. The third argument is elapsed seconds since that effect's
68
+ last draw (initially zero, capped at 0.25); the fourth is `{scale, fps}`.
69
+ Return `true` to continue animating; any other return removes an animated effect.
70
+
71
+ ```js
72
+ const governor = createEffectGovernor({
73
+ watchVisibility: true,
74
+ watchReducedMotion: true,
75
+ });
76
+ const remove = governor.add(
77
+ 'background',
78
+ (time, state, elapsedSeconds, quality) => {
79
+ paintBackground(elapsedSeconds, quality.scale);
80
+ return true;
81
+ },
82
+ { fps: 30, onQualityChange: ({ scale }) => resizeBackingStore(scale) }
83
+ );
84
+ governor.set({ motion: 'auto' });
85
+ // After a resize or option change, repaint once even if motion is off:
86
+ governor.invalidate('background');
87
+ // Read a detached snapshot at any time while the effect is registered:
88
+ console.log(governor.getQuality('background'));
89
+ remove();
90
+ governor.dispose();
91
+ ```
92
+
93
+ Each effect watches all animation frames, including frames skipped by its cap.
94
+ Gaps above 45 ms are slow; gaps at or below zero or above 1000 ms are ignored.
95
+ Windows close after 30 valid gaps or 1000 accumulated milliseconds. The first
96
+ window is warm-up. A strict slow majority lowers quality once per window:
97
+ resolution multiplies by `scaleFactor` (default 0.7, rounded to three decimals)
98
+ until `minScale` (0.4), then frame-rate share multiplies by `fpsFactor` (0.5)
99
+ until `minFps` (0.25). Quality never increases. These four per-effect options
100
+ accept positive numbers up to one; factors must be below one. `resolution: false`
101
+ keeps scale at one and lowers only frame rate.
102
+
103
+ An optional `fps` target of 5..60 throttles draws to
104
+ `1000 / (fps * quality.fps)` milliseconds; omitting it preserves drawing on every
105
+ animation frame at full quality, with a 60 fps base when quality lowers the
106
+ frame-rate share. `onQualityChange` receives a detached snapshot once per step,
107
+ before drawing, allowing a backing store to resize only when necessary.
108
+
109
+ Motion defaults to off. `auto` follows reduced motion, `on` overrides reduced
110
+ motion explicitly, and `off` never animates. Legacy booleans still work: `true`
111
+ follows reduced motion and `false` pauses. Hidden pages always pause. Pause and
112
+ resume reset timestamps and start a new warm-up window, retaining quality.
113
+ `invalidate` coalesces requests into one next-frame draw with elapsed zero,
114
+ bypasses the cap, and preserves a paused effect regardless of its return value.
115
+ It never enables motion. Unknown IDs are ignored. Removing/replacing an effect
116
+ starts a new quality session; an old removal callback cannot remove a replacement.
117
+
118
+ Automatic visibility and reduced-motion subscriptions are opt-in. Tests or hosts
119
+ can inject `document` and `matchMedia` alongside `requestFrame` and `cancelFrame`.
120
+ Without browser sources, the governor still works with manual `set` inputs.
121
+ `dispose` cancels pending frames and removes both listeners. Sound remains
122
+ controlled independently by `sound`, `volume`, and visibility.
package/package.json CHANGED
@@ -1,6 +1,54 @@
1
1
  {
2
2
  "name": "@link-foundation/ui-themes",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Links Notation theme packages for the associative UI framework",
5
+ "type": "module",
6
+ "exports": {
7
+ ".": {
8
+ "types": "./src/index.d.ts",
9
+ "default": "./src/index.js"
10
+ },
11
+ "./themes/*": "./themes/*",
12
+ "./classic/frames": {
13
+ "types": "./src/classic/frames.d.ts",
14
+ "default": "./src/classic/frames.js"
15
+ },
16
+ "./classic/materials": {
17
+ "types": "./src/classic/materials.d.ts",
18
+ "default": "./src/classic/materials.js"
19
+ }
20
+ },
21
+ "files": [
22
+ "src/",
23
+ "themes/",
24
+ "README.md",
25
+ "LICENSE"
26
+ ],
27
+ "license": "Unlicense",
28
+ "repository": {
29
+ "type": "git",
30
+ "url": "git+https://github.com/link-foundation/ui.git",
31
+ "directory": "packages/ui-themes"
32
+ },
33
+ "homepage": "https://github.com/link-foundation/ui/tree/main/packages/ui-themes#readme",
34
+ "bugs": {
35
+ "url": "https://github.com/link-foundation/ui/issues"
36
+ },
37
+ "engines": {
38
+ "node": ">=20"
39
+ },
40
+ "dependencies": {
41
+ "@link-foundation/ui-tokens": "^0.1.0",
42
+ "@material/material-color-utilities": "0.3.0",
43
+ "@link-foundation/ui-core": "^0.1.0"
44
+ },
45
+ "publishConfig": {
46
+ "access": "public"
47
+ },
48
+ "devDependencies": {
49
+ "jsdom": "^30.1.3",
50
+ "links-notation": "^0.27.1",
51
+ "prettier": "^3.6.2",
52
+ "@fluentui/tokens": "1.0.0-alpha.24"
53
+ }
54
+ }
@@ -0,0 +1,193 @@
1
+ /** Theme IDs and their canonical LiNo sources. */
2
+ export const classicThemes = [
3
+ {
4
+ id: 'deepcase-classic',
5
+ path: 'classic/deepcase/classic.lino',
6
+ family: 'deepcase',
7
+ },
8
+ {
9
+ id: 'deepcase-dark',
10
+ path: 'classic/deepcase/dark.lino',
11
+ family: 'deepcase',
12
+ },
13
+ {
14
+ id: 'deepcase-perception',
15
+ path: 'classic/deepcase/perception.lino',
16
+ family: 'deepcase',
17
+ },
18
+ {
19
+ id: 'deepcase-2025',
20
+ path: 'classic/deepcase/2025.lino',
21
+ family: 'deepcase',
22
+ },
23
+ {
24
+ id: 'deepcase-landing',
25
+ path: 'classic/deepcase/landing.lino',
26
+ family: 'deepcase',
27
+ },
28
+ {
29
+ id: 'glass',
30
+ path: 'classic/konard/glass.lino',
31
+ family: 'konard',
32
+ },
33
+ {
34
+ id: 'liquid',
35
+ path: 'classic/konard/liquid.lino',
36
+ family: 'konard',
37
+ },
38
+ {
39
+ id: 'futuristic',
40
+ path: 'classic/konard/futuristic.lino',
41
+ family: 'konard',
42
+ },
43
+ {
44
+ id: 'immortality-mission',
45
+ path: 'classic/immortality/palettes.lino',
46
+ family: 'immortality',
47
+ },
48
+ {
49
+ id: 'immortality-glitchy',
50
+ path: 'classic/immortality/palettes.lino',
51
+ family: 'immortality',
52
+ },
53
+ {
54
+ id: 'immortality-amber',
55
+ path: 'classic/immortality/palettes.lino',
56
+ family: 'immortality',
57
+ },
58
+ {
59
+ id: 'immortality-monochrome',
60
+ path: 'classic/immortality/palettes.lino',
61
+ family: 'immortality',
62
+ },
63
+ {
64
+ id: 'immortality-tron',
65
+ path: 'classic/immortality/palettes.lino',
66
+ family: 'immortality',
67
+ },
68
+ {
69
+ id: 'immortality-ares',
70
+ path: 'classic/immortality/palettes.lino',
71
+ family: 'immortality',
72
+ },
73
+ {
74
+ id: 'immortality-clu',
75
+ path: 'classic/immortality/palettes.lino',
76
+ family: 'immortality',
77
+ },
78
+ {
79
+ id: 'immortality-athena',
80
+ path: 'classic/immortality/palettes.lino',
81
+ family: 'immortality',
82
+ },
83
+ {
84
+ id: 'immortality-aphrodite',
85
+ path: 'classic/immortality/palettes.lino',
86
+ family: 'immortality',
87
+ },
88
+ {
89
+ id: 'immortality-poseidon',
90
+ path: 'classic/immortality/palettes.lino',
91
+ family: 'immortality',
92
+ },
93
+ {
94
+ id: 'immortality-soulextract',
95
+ path: 'classic/immortality/palettes.lino',
96
+ family: 'immortality',
97
+ },
98
+ {
99
+ id: 'immortality-matrix',
100
+ path: 'classic/immortality/palettes.lino',
101
+ family: 'immortality',
102
+ },
103
+ {
104
+ id: 'poseidon',
105
+ path: 'classic/immortality/poseidon.lino',
106
+ family: 'immortality',
107
+ },
108
+ {
109
+ id: 'arwes',
110
+ path: 'classic/immortality/arwes.lino',
111
+ family: 'immortality',
112
+ },
113
+ {
114
+ id: 'quiet',
115
+ path: 'classic/immortality/quiet.lino',
116
+ family: 'immortality',
117
+ },
118
+ {
119
+ id: 'fa-flat',
120
+ path: 'classic/formal-ai/fa-flat.lino',
121
+ family: 'formal-ai',
122
+ },
123
+ {
124
+ id: 'fa-glass',
125
+ path: 'classic/formal-ai/fa-glass.lino',
126
+ family: 'formal-ai',
127
+ },
128
+ {
129
+ id: 'fa-material',
130
+ path: 'classic/formal-ai/fa-material.lino',
131
+ family: 'formal-ai',
132
+ },
133
+ {
134
+ id: 'fa-contrast',
135
+ path: 'classic/formal-ai/fa-contrast.lino',
136
+ family: 'formal-ai',
137
+ },
138
+ {
139
+ id: 'chat-cards',
140
+ path: 'classic/formal-ai/chat-cards.lino',
141
+ family: 'formal-ai',
142
+ },
143
+ {
144
+ id: 'chat-compact',
145
+ path: 'classic/formal-ai/chat-compact.lino',
146
+ family: 'formal-ai',
147
+ },
148
+ {
149
+ id: 'chat-bubbles',
150
+ path: 'classic/formal-ai/chat-bubbles.lino',
151
+ family: 'formal-ai',
152
+ },
153
+ {
154
+ id: 'composer-flat',
155
+ path: 'classic/formal-ai/composer.lino',
156
+ family: 'formal-ai',
157
+ },
158
+ {
159
+ id: 'composer-glass-soft',
160
+ path: 'classic/formal-ai/composer.lino',
161
+ family: 'formal-ai',
162
+ },
163
+ {
164
+ id: 'composer-glass-clear',
165
+ path: 'classic/formal-ai/composer.lino',
166
+ family: 'formal-ai',
167
+ },
168
+ {
169
+ id: 'composer-bubble',
170
+ path: 'classic/formal-ai/composer.lino',
171
+ family: 'formal-ai',
172
+ },
173
+ {
174
+ id: 'chat-t3',
175
+ path: 'classic/meta-sovereign/chat-t3.lino',
176
+ family: 'meta-sovereign',
177
+ },
178
+ {
179
+ id: 'chat-telegram',
180
+ path: 'classic/meta-sovereign/chat-telegram.lino',
181
+ family: 'meta-sovereign',
182
+ },
183
+ {
184
+ id: 'chat-whatsapp',
185
+ path: 'classic/meta-sovereign/chat-whatsapp.lino',
186
+ family: 'meta-sovereign',
187
+ },
188
+ {
189
+ id: 'chat-signal',
190
+ path: 'classic/meta-sovereign/chat-signal.lino',
191
+ family: 'meta-sovereign',
192
+ },
193
+ ];
@@ -0,0 +1,199 @@
1
+ import { createQualityWatcher } from './effect-quality.js';
2
+
3
+ function makeEffect(draw, options) {
4
+ const fps = options.fps ?? 60;
5
+ if (!Number.isFinite(fps) || fps < 5 || fps > 60) {
6
+ throw new RangeError('Effect fps must be between 5 and 60');
7
+ }
8
+ return {
9
+ draw,
10
+ fps,
11
+ capped: options.fps !== undefined,
12
+ watcher: createQualityWatcher(options),
13
+ onQualityChange: options.onQualityChange ?? (() => {}),
14
+ previous: null,
15
+ lastDraw: null,
16
+ invalid: false,
17
+ };
18
+ }
19
+
20
+ function resetEffects(effects) {
21
+ for (const effect of effects.values()) {
22
+ effect.previous = null;
23
+ effect.lastDraw = null;
24
+ effect.watcher.reset();
25
+ }
26
+ }
27
+
28
+ function drawEffect(effect, time, state, moving) {
29
+ const gap = effect.previous === null ? 0 : time - effect.previous;
30
+ effect.previous = moving ? time : null;
31
+ if (moving && effect.watcher.feed(gap)) {
32
+ effect.onQualityChange(effect.watcher.snapshot());
33
+ }
34
+ const shares = effect.watcher.snapshot();
35
+ const sinceDraw = effect.lastDraw === null ? 0 : time - effect.lastDraw;
36
+ const invalid = effect.invalid;
37
+ if (
38
+ !invalid &&
39
+ (effect.capped || shares.fps < 1) &&
40
+ effect.lastDraw !== null &&
41
+ sinceDraw + 1e-7 < 1000 / (effect.fps * shares.fps)
42
+ ) {
43
+ return true;
44
+ }
45
+ effect.invalid = false;
46
+ const elapsed =
47
+ invalid || effect.lastDraw === null
48
+ ? 0
49
+ : Math.max(0, Math.min(0.25, sinceDraw / 1000));
50
+ effect.lastDraw = moving ? time : null;
51
+ return effect.draw(time, { ...state }, elapsed, shares) === true;
52
+ }
53
+
54
+ function watchInputs(options, set) {
55
+ const cleanups = [];
56
+ const listen = (source, event, update) => {
57
+ if (!source) {
58
+ return;
59
+ }
60
+ source.addEventListener(event, update);
61
+ cleanups.push(() => source.removeEventListener(event, update));
62
+ update();
63
+ };
64
+ if (options.watchVisibility) {
65
+ const document = options.document ?? globalThis.document;
66
+ listen(document, 'visibilitychange', () =>
67
+ set({ visible: !document.hidden })
68
+ );
69
+ }
70
+ if (options.watchReducedMotion) {
71
+ const media = (
72
+ options.matchMedia ?? globalThis.matchMedia?.bind(globalThis)
73
+ )?.('(prefers-reduced-motion: reduce)');
74
+ listen(media, 'change', () => set({ reducedMotion: media.matches }));
75
+ }
76
+ return () => {
77
+ for (const cleanup of cleanups) {
78
+ cleanup();
79
+ }
80
+ };
81
+ }
82
+
83
+ /** Opt-in scheduler with independent, monotonically decreasing effect quality. */
84
+ export function createEffectGovernor(options = {}) {
85
+ const {
86
+ requestFrame = (fn) => globalThis.requestAnimationFrame(fn),
87
+ cancelFrame = (id) => globalThis.cancelAnimationFrame(id),
88
+ onSound = () => {},
89
+ } = options;
90
+ let state = {
91
+ motion: false,
92
+ reducedMotion: false,
93
+ visible: true,
94
+ sound: false,
95
+ volume: 0,
96
+ };
97
+ let pending = null;
98
+ let disposed = false;
99
+ const effects = new Map();
100
+ const assertLive = () => {
101
+ if (disposed) {
102
+ throw new Error('Effect governor is disposed');
103
+ }
104
+ };
105
+ const enabled = () =>
106
+ !disposed &&
107
+ state.visible &&
108
+ (state.motion === 'on' ||
109
+ ((state.motion === true || state.motion === 'auto') &&
110
+ !state.reducedMotion));
111
+ const cancel = () => {
112
+ if (pending !== null) {
113
+ cancelFrame(pending);
114
+ pending = null;
115
+ }
116
+ };
117
+ const hasWork = () =>
118
+ !disposed &&
119
+ effects.size &&
120
+ (enabled() || [...effects.values()].some((effect) => effect.invalid));
121
+ const schedule = () => {
122
+ if (pending === null && hasWork()) {
123
+ pending = requestFrame(tick);
124
+ }
125
+ };
126
+ function tick(time) {
127
+ pending = null;
128
+ for (const [id, effect] of effects) {
129
+ const moving = enabled();
130
+ if (disposed || (!moving && !effect.invalid)) {
131
+ continue;
132
+ }
133
+ const keep = drawEffect(effect, time, state, moving);
134
+ if (moving && !keep && effects.get(id) === effect) {
135
+ effects.delete(id);
136
+ }
137
+ }
138
+ schedule();
139
+ }
140
+ function set(patch) {
141
+ assertLive();
142
+ const next = { ...state, ...patch };
143
+ if (!Number.isFinite(next.volume) || next.volume < 0 || next.volume > 1) {
144
+ throw new RangeError('Sound volume must be between zero and one');
145
+ }
146
+ if (![true, false, 'auto', 'on', 'off'].includes(next.motion)) {
147
+ throw new TypeError('Motion must be boolean, auto, on or off');
148
+ }
149
+ const wasEnabled = enabled();
150
+ state = next;
151
+ if (wasEnabled !== enabled()) {
152
+ resetEffects(effects);
153
+ }
154
+ if (!hasWork()) {
155
+ cancel();
156
+ }
157
+ schedule();
158
+ }
159
+ const unwatch = watchInputs(options, set);
160
+ return {
161
+ set,
162
+ add(id, draw, effectOptions = {}) {
163
+ assertLive();
164
+ const effect = makeEffect(draw, effectOptions);
165
+ effects.set(id, effect);
166
+ schedule();
167
+ return () => {
168
+ if (effects.get(id) === effect) {
169
+ effects.delete(id);
170
+ }
171
+ if (!hasWork()) {
172
+ cancel();
173
+ }
174
+ };
175
+ },
176
+ getQuality(id) {
177
+ return effects.get(id)?.watcher.snapshot();
178
+ },
179
+ invalidate(id) {
180
+ assertLive();
181
+ const effect = effects.get(id);
182
+ if (effect) {
183
+ effect.invalid = true;
184
+ schedule();
185
+ }
186
+ },
187
+ sound(event) {
188
+ if (!disposed && state.visible && state.sound && state.volume > 0) {
189
+ onSound(event, state.volume);
190
+ }
191
+ },
192
+ dispose() {
193
+ disposed = true;
194
+ unwatch();
195
+ cancel();
196
+ effects.clear();
197
+ },
198
+ };
199
+ }
@@ -0,0 +1,76 @@
1
+ /** Internal per-effect watcher. Only valid frame gaps contribute to windows. */
2
+ export function createQualityWatcher({
3
+ resolution = true,
4
+ minScale = 0.4,
5
+ scaleFactor = 0.7,
6
+ minFps = 0.25,
7
+ fpsFactor = 0.5,
8
+ } = {}) {
9
+ for (const [name, value] of Object.entries({
10
+ minScale,
11
+ scaleFactor,
12
+ minFps,
13
+ fpsFactor,
14
+ })) {
15
+ if (
16
+ !Number.isFinite(value) ||
17
+ value <= 0 ||
18
+ value > 1 ||
19
+ ((name === 'scaleFactor' || name === 'fpsFactor') && value === 1)
20
+ ) {
21
+ throw new RangeError(`Invalid quality option ${name}`);
22
+ }
23
+ }
24
+ let scale = 1,
25
+ fps = 1;
26
+ let frames = 0,
27
+ duration = 0,
28
+ slow = 0,
29
+ warmup = true;
30
+ const resetWindow = () => {
31
+ frames = 0;
32
+ duration = 0;
33
+ slow = 0;
34
+ };
35
+ const snapshot = () => ({ scale, fps });
36
+ return {
37
+ snapshot,
38
+ reset() {
39
+ resetWindow();
40
+ warmup = true;
41
+ },
42
+ feed(gap) {
43
+ if (!Number.isFinite(gap) || gap <= 0 || gap > 1000) {
44
+ return false;
45
+ }
46
+ frames++;
47
+ duration += gap;
48
+ if (gap > 45) {
49
+ slow++;
50
+ }
51
+ if (frames < 30 && duration < 1000) {
52
+ return false;
53
+ }
54
+ const struggling = !warmup && slow > frames / 2;
55
+ warmup = false;
56
+ resetWindow();
57
+ if (!struggling) {
58
+ return false;
59
+ }
60
+ const before = snapshot();
61
+ if (resolution && scale > minScale) {
62
+ // Rounding must not raise a share or pass a configured floor.
63
+ scale = Math.max(
64
+ minScale,
65
+ Math.min(scale, Math.round(scale * scaleFactor * 1000) / 1000)
66
+ );
67
+ if (scale === before.scale) {
68
+ scale = minScale;
69
+ }
70
+ } else {
71
+ fps = Math.max(minFps, fps * fpsFactor);
72
+ }
73
+ return scale < before.scale || fps < before.fps;
74
+ },
75
+ };
76
+ }