@occluze/umber 0.2.1 → 0.3.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 (84) hide show
  1. package/LICENSE.md +21 -0
  2. package/README.md +78 -48
  3. package/dist/chunks/badge.js +2 -0
  4. package/dist/chunks/basis.js +2 -0
  5. package/dist/chunks/basis_transcoder.js +2 -0
  6. package/dist/chunks/basis_transcoder.wasm +0 -0
  7. package/dist/chunks/capture.js +2 -2
  8. package/dist/chunks/covers.js +2 -2
  9. package/dist/chunks/curves.js +2 -0
  10. package/dist/chunks/flip.js +2 -2
  11. package/dist/chunks/fx.js +2 -102
  12. package/dist/chunks/gl.js +2 -180
  13. package/dist/chunks/glsl.js +2 -239
  14. package/dist/chunks/inspect.js +2 -6
  15. package/dist/chunks/instances.js +2 -93
  16. package/dist/chunks/layers.js +2 -21
  17. package/dist/chunks/licence.js +2 -2
  18. package/dist/chunks/morph.js +2 -2
  19. package/dist/chunks/patch.js +2 -0
  20. package/dist/chunks/prepared.js +2 -0
  21. package/dist/chunks/profiler.js +2 -0
  22. package/dist/chunks/restore.js +2 -2
  23. package/dist/chunks/shapes.js +2 -2
  24. package/dist/chunks/sim.js +2 -22
  25. package/dist/chunks/text.js +2 -52
  26. package/dist/chunks/video.js +2 -2
  27. package/dist/chunks/views.js +2 -2
  28. package/dist/chunks/vocabulary.js +2 -0
  29. package/dist/chunks/warm.js +2 -2
  30. package/dist/frameworks/astro.mjs +2 -0
  31. package/dist/frameworks/react.mjs +2 -0
  32. package/dist/frameworks/svelte.mjs +2 -0
  33. package/dist/frameworks/vue.mjs +2 -0
  34. package/dist/modules/debug.js +2 -36
  35. package/dist/modules/debug.mjs +2 -36
  36. package/dist/modules/handoff.js +2 -2
  37. package/dist/modules/handoff.mjs +2 -2
  38. package/dist/modules/input.js +2 -2
  39. package/dist/modules/input.mjs +2 -2
  40. package/dist/modules/router-swap.js +2 -13
  41. package/dist/modules/router.js +2 -2
  42. package/dist/modules/router.mjs +2 -2
  43. package/dist/modules/scroll-more.js +2 -0
  44. package/dist/modules/scroll-touch.js +2 -0
  45. package/dist/modules/scroll.js +2 -2
  46. package/dist/modules/scroll.mjs +2 -2
  47. package/dist/modules/scrollfx.js +2 -0
  48. package/dist/modules/scrollfx.mjs +2 -0
  49. package/dist/modules/scrub.js +2 -8
  50. package/dist/modules/scrub.mjs +2 -8
  51. package/dist/modules/three.js +2 -0
  52. package/dist/modules/three.mjs +2 -0
  53. package/dist/node/assets.mjs +9 -0
  54. package/dist/node/astro.mjs +47 -0
  55. package/dist/node/cli.mjs +109 -0
  56. package/dist/node/shared-3Q24RNIF.mjs +602 -0
  57. package/dist/node/shared-4FIU6DYP.mjs +200 -0
  58. package/dist/node/vite.mjs +10 -0
  59. package/dist/umber.css +2 -2
  60. package/dist/umber.js +2 -2
  61. package/dist/umber.mjs +2 -2
  62. package/docs/AI-quick.md +116 -54
  63. package/docs/AI.md +1275 -805
  64. package/docs/npm.md +37 -26
  65. package/package.json +181 -12
  66. package/types/assets.d.ts +87 -0
  67. package/types/astro.d.ts +43 -0
  68. package/types/debug.d.ts +17 -16
  69. package/types/esm.d.ts +12 -12
  70. package/types/global.d.ts +17 -0
  71. package/types/handoff.d.ts +26 -25
  72. package/types/input.d.ts +63 -55
  73. package/types/loop.d.ts +75 -0
  74. package/types/module.d.ts +108 -0
  75. package/types/react.d.ts +15 -0
  76. package/types/router.d.ts +87 -45
  77. package/types/scroll.d.ts +96 -38
  78. package/types/scrollfx.d.ts +80 -0
  79. package/types/scrub.d.ts +33 -32
  80. package/types/svelte.d.ts +16 -0
  81. package/types/three.d.ts +226 -0
  82. package/types/umber.d.ts +633 -357
  83. package/types/vite.d.ts +33 -0
  84. package/types/vue.d.ts +14 -0
package/types/umber.d.ts CHANGED
@@ -1,63 +1,74 @@
1
- // -----------------------------------------
2
- // UMBER: PUBLIC TYPES FOR SITE CODE
3
- // -----------------------------------------
4
-
5
- // Editor autocomplete and type checks for site code (VS Code, Astro, Vite, TS or
6
- // checkJs projects). Nothing here runs.
7
- //
8
- // <script src=".../umber@x.y.z/umber.js"> -> window.Umber: { version, createGL, math, use }
9
- // import { createGL } from "@occluze/umber" (types/esm.d.ts)
10
- //
11
- // For the <script> tag: copy this file into your project (e.g. src/types/umber.d.ts) and
12
- // list it in tsconfig/jsconfig "include", or add /// <reference path="./types/umber.d.ts" />.
13
- //
14
- // Hand-written on purpose: one readable file, also the most compact exact API reference
15
- // to paste into an AI assistant. Keep it in step with src/types.ts and src/core/create.ts
16
- // (test/types.test.ts checks the members of Umber and of the engine).
17
- //
18
- // ATTRIBUTE CHEAT SHEET (the DOM is the API)
19
- //
20
- // data-gl="image | video | text | shader | layer | group" make this element a GPU plane
21
- // (group: draws the GL planes inside it as one, through
22
- // its own data-gl-effect; docs/ai/groups.md)
23
- // data-gl-pass="grade grain" effects run over the whole GL frame (on <html> or <body>)
24
- // or over one group; per effect -blend, -opacity, -scale
25
- // data-gl-effect="ripple tint" effects (defined with gl.effect), applied in order
26
- // data-gl-<effect>-<option>="1.2" an effect option (also --gl-<effect>-<option> in CSS)
27
- // data-gl-<effect>-trigger auto (default) | scroll | load | manual | hover, for effects with `play`
28
- // data-gl-<effect>-delay / -duration / -ease / -start the play's timing ("top 90%")
29
- // data-gl-shader="name" with data-gl="shader": the gl.shader() it draws
30
- // data-gl-layer="name" with data-gl="layer": the gl.layer() it runs
31
- // data-gl-src="url" another image than the <img> inside
32
- // data-gl-fit="cover|contain|fill" object-fit for the texture
33
- // data-gl-live measure every frame (sticky, fixed or transformed parents)
34
- // data-gl-clip="false" draw it without its parents' clips (overflow, clip-path, masks)
35
- // data-gl-wrap="x | y" on a track: its planes wrap around it (an endless gallery)
36
- // data-gl-order="1" draw order
37
- // data-gl-instances="64" drawn many times in one call: "64", "tiles 24x16",
38
- // "chars" | "words" | "lines" (GL text), "echo 6", "ink 3000"
39
- // data-gl-placeholder="UF…" a blurred preview until the image loads (chunks/warm.js;
40
- // make it with gl.placeholder(src))
41
- // data-gl-id="hero" the same id on two pages: the image flies across (morph),
42
- // with any router (gl.transition() makes it tighter)
43
- // data-gl-morph-duration="1" / -ease on the element you go to: the flight's timing
44
- // (also --gl-morph-duration / --gl-morph-ease in CSS)
45
- // data-gl-shader-<option> / data-gl-layer-<option> a gl.shader() / gl.layer() option
46
- // data-gl-above a DOM element that must sit on top of the canvas
47
- // data-gl-disable (on <body>) GL off for this page
48
- // data-gl-host where the canvas goes (else Umber makes one)
49
- // data-gl-video-autopause="false" keep a muted loop video playing off screen
50
- // data-gl-scrub (+ -start, -end, -track, -smooth, -source, -frames...) scroll-scrubbed
51
- // video: needs the scrub module (types/scrub.d.ts)
52
- // Modules (same version as umber.js): modules/scrub.js (types/scrub.d.ts) and
53
- // modules/debug.js, the HUD, outlines and markers (types/debug.d.ts).
54
- // gl.inspect(el) prints why an element is (not) drawn.
55
- // Events also go to document: umber:ready (detail = the engine), umber:lost,
56
- // umber:restored, umber:destroy.
57
- // From JS: gl.add(el, { type, effects, options }) writes these attributes for you.
58
- // Written by Umber: html.has-gl, data-gl-status="loading|ready|error", data-gl-media,
59
- // data-gl-play, data-gl-morphing, data-gl-canvas on the canvas, and
60
- // data-gl-view="loading|ready|off|error|lost" on gl.attach() / gl.view() elements.
1
+ /**
2
+ * Umber's public types for site code.
3
+ *
4
+ * Editor autocomplete and type checks for site code (VS Code, Astro, Vite, TS or
5
+ * checkJs projects). Nothing here runs.
6
+ *
7
+ * <script src=".../umber@x.y.z/umber.js"> -> window.Umber: { version, createUmber, math, use }
8
+ * import { createUmber } from "@occluze/umber" (types/esm.d.ts)
9
+ *
10
+ * For the <script> tag: copy this file and global.d.ts (window.Umber and the global
11
+ * `Umber`) into your project (e.g. src/types/) and list both in tsconfig/jsconfig
12
+ * "include", or add /// <reference path="./types/global.d.ts" />. With the npm package
13
+ * installed: /// <reference types="@occluze/umber/global" />. An `import` from
14
+ * "@occluze/umber" gets no window.Umber: the npm build never sets it.
15
+ *
16
+ * Hand-written on purpose: one readable file, also the most compact exact API reference
17
+ * to paste into an AI assistant. Keep it in step with src/types.ts and src/core/create.ts
18
+ * (test/types/types.test.ts checks the members of Umber and of the engine).
19
+ *
20
+ * Attribute cheat sheet (the DOM is the API). An element says what it is, how it behaves,
21
+ * and what it's set to: data-umber="<kind> <behaviours>", then one attribute per setting.
22
+ *
23
+ * kinds, one: image | video | text | shader | layer | model | group (a GPU plane)
24
+ * container | wrapper (router), scroller (the element that scrolls)
25
+ * behaviours: above, pin, horizontal, inview (scrollfx), skip (router), nested (scroll)
26
+ * with a value, the long form only: data-umber-pin="80px", data-umber-inview="shown"
27
+ *
28
+ * data-umber="group" draws the GL planes inside it as one, through its
29
+ * own data-umber-effect (docs/ai/groups.md)
30
+ * data-umber-pass="grade grain" effects run over the whole GL frame (on <html> or <body>)
31
+ * or over one group; per effect -blend, -opacity, -scale
32
+ * data-umber-effect="ripple tint" effects (defined with umber.effect), applied in order
33
+ * data-umber-<effect>-<option>="1.2" an effect option (also --umber-<effect>-<option> in CSS)
34
+ * data-umber-<effect>-trigger auto (default) | scroll | load | manual | hover, for effects with `play`
35
+ * data-umber-<effect>-delay / -duration / -ease / -start the play's timing ("top 90%")
36
+ * data-umber-<effect>-repeat "reverse" | "true": plays again
37
+ * data-umber-shader="name" with data-umber="shader": the umber.shader() it draws
38
+ * data-umber-layer="name" with data-umber="layer": the umber.layer() it runs
39
+ * data-umber-src="url" another image than the <img> inside
40
+ * data-umber-fit="cover|contain|fill" object-fit for the texture
41
+ * data-umber-live measure every frame (sticky, fixed or transformed parents)
42
+ * data-umber-clip="false" draw it without its parents' clips (overflow, clip-path, masks)
43
+ * data-umber-wrap="x | y" on a track: its planes wrap around it (an endless gallery)
44
+ * data-umber-order="1" draw order
45
+ * data-umber-instances="64" drawn many times in one call: "64", "tiles 24x16",
46
+ * "chars" | "words" | "lines" (GL text), "echo 6", "ink 3000",
47
+ * "points 20000"
48
+ * data-umber-placeholder="UF…" a blurred preview until the image loads (chunks/warm.js;
49
+ * make it with umber.placeholder(src))
50
+ * data-umber-id="hero" the same id on two pages: the image flies across (morph),
51
+ * with any router (umber.transition() makes it tighter)
52
+ * data-umber-morph-duration="1" / -ease on the element you go to: the flight's timing
53
+ * (also --umber-morph-duration / --umber-morph-ease in CSS)
54
+ * data-umber-shader-<option> / data-umber-layer-<option> a umber.shader() / umber.layer() option
55
+ * data-umber="above" a DOM element that must sit on top of the canvas
56
+ * data-umber-disable (on <body>) GL off for this page
57
+ * data-umber-host where the canvas goes (else Umber makes one)
58
+ * data-umber-video-autopause="false" keep a muted loop video playing off screen
59
+ * data-umber-scrub (+ -start, -end, -track, -smooth, -source, -frames...) scroll-scrubbed
60
+ * video: needs the scrub module (types/scrub.d.ts)
61
+ * Modules (same version as umber.js): modules/scrub.js (types/scrub.d.ts) and
62
+ * modules/debug.js, the HUD, outlines and markers (types/debug.d.ts).
63
+ * umber.inspect(el) prints why an element is (not) drawn.
64
+ * Events also go to document (payload in event.detail): umber:ready (the engine), umber:lost,
65
+ * umber:restored, umber:destroy, umber:added (the roots that entered the page),
66
+ * umber:off ({ reason }) and umber:fallback ({ el, reason }).
67
+ * From JS: umber.add(el, { type, effects, options }) writes these attributes for you.
68
+ * Written by Umber: html.has-umber, data-umber-status="loading|ready|error", data-umber-media,
69
+ * data-umber-play, data-umber-morphing, data-umber-canvas on the canvas, and
70
+ * data-umber-view="loading|ready|off|error|lost" on umber.attach() / umber.view() elements.
71
+ */
61
72
 
62
73
  /**
63
74
  * The next page, as a router hands it over: its HTML, a parsed Document, its container
@@ -70,27 +81,28 @@ export type NextPage =
70
81
  | { html?: string }
71
82
  | null
72
83
  | undefined
73
- | PromiseLike<string | ParentNode | { html?: string } | null | undefined | void>;
84
+ | PromiseLike<string | ParentNode | { html?: string } | null | undefined>;
74
85
 
75
86
  /** A plain { value } anyone can animate (GSAP, Motion, your own code) or read. */
76
87
  export interface Signal<T = number> {
77
88
  value: T;
78
89
  }
79
90
 
80
- export interface LenisLike {
91
+ /** What Umber reads of a smooth-scroll instance (Lenis, or any with the same shape). Its scroll handler takes nothing: it reads the position itself. */
92
+ export interface SmoothScrollLike {
81
93
  animatedScroll?: number;
82
94
  scroll?: number;
83
95
  velocity?: number;
84
96
  isHorizontal?: boolean;
85
97
  options?: { wrapper?: Window | Element; orientation?: string };
86
- on(event: "scroll", fn: (...args: any[]) => void): unknown;
87
- off?(event: "scroll", fn: (...args: any[]) => void): unknown;
98
+ on(event: "scroll", fn: () => void): unknown;
99
+ off?(event: "scroll", fn: () => void): unknown;
88
100
  }
89
101
 
90
102
  export interface ScrollObject {
91
103
  x?: number | (() => number);
92
104
  y?: number | (() => number);
93
- /** px per frame, like Lenis. Omit it to let Umber work it out from the position. */
105
+ /** px per frame. Omit it to let Umber work it out from the position. */
94
106
  velocity?: number | (() => number);
95
107
  }
96
108
 
@@ -104,47 +116,61 @@ export interface Env {
104
116
  readonly designer: boolean;
105
117
  }
106
118
 
107
- export interface GLOptions {
119
+ export interface UmberOptions {
120
+ /** Your account's public key, from your occluze dashboard. Also data-umber-key on the umber.js tag. */
121
+ key?: string;
108
122
  /**
109
123
  * Where Umber reads scroll from, read-only: it never creates, drives or configures it.
110
124
  * The default also follows <body> when it is the page's scroller (html { overflow: hidden }).
111
125
  * @default window
112
- * @example createGL({ scroll: lenis }) // your Lenis instance
113
- * @example createGL({ scroll: document.querySelector(".scroller") })
114
- * @example createGL({ scroll: { y: () => myScroll.y } }) // anything else
126
+ * @example createUmber({ scroll: lenis }) // your Lenis instance
127
+ * @example createUmber({ scroll: document.querySelector(".scroller") })
128
+ * @example createUmber({ scroll: { y: () => myScroll.y } }) // anything else
115
129
  */
116
- scroll?: Window | Element | LenisLike | ScrollObject | null;
130
+ scroll?: Window | Element | SmoothScrollLike | ScrollObject | null;
117
131
  /**
118
132
  * "auto": Umber runs its own requestAnimationFrame loop, which sleeps when nothing moves.
119
- * false: nothing runs until you call gl.render(time) from your own loop.
133
+ * false: nothing runs until you call umber.render(time) from your own loop.
120
134
  * @default "auto"
121
- * @example createGL({ loop: false }); gsap.ticker.add((t) => gl.render(t * 1000));
135
+ * @example createUmber({ loop: false }); gsap.ticker.add((t) => umber.render(t * 1000));
122
136
  */
123
137
  loop?: "auto" | false;
138
+ /**
139
+ * One clock for the whole page: the page's own requestAnimationFrame loops (GSAP's ticker,
140
+ * Lenis, three.js, Motion, minified code) run inside Umber's frame, one requestAnimationFrame
141
+ * per frame: Lenis first, then the page's loops, then Umber reads and draws. A Lenis that
142
+ * runs its own loop (autoRaf) and window.gsap are driven through their own APIs. The loop
143
+ * still sleeps when nothing asks for frames. Without code: data-umber-patch on umber.js's
144
+ * script tag (patched as the script runs, so loops started before createUmber() are caught).
145
+ * @default false
146
+ * @example createUmber({ scroll: lenis, patch: true })
147
+ * @example createUmber({ patch: { gsap } }) // a bundled GSAP, not on window
148
+ */
149
+ patch?: boolean | { gsap?: GsapLike };
124
150
  /**
125
151
  * Which devices draw DOM planes in GL (the rest keep the plain DOM, and nothing downloads).
126
152
  * "desktop" = hover + fine pointer + at least 768 px wide. Anything else is "desktop", with a warning.
127
153
  * @default "all"
128
- * @example createGL({ devices: "desktop" })
129
- * @example createGL({ devices: (env) => !env.isTouch })
154
+ * @example createUmber({ devices: "desktop" })
155
+ * @example createUmber({ devices: (env) => !env.isTouch })
130
156
  */
131
157
  devices?: "all" | "desktop" | false | ((env: Env) => boolean);
132
158
  /**
133
- * Effects only where this CSS media query matches, read when the page loads. Without code: data-gl-media on <body>.
134
- * @example createGL({ media: "(min-width: 900px)" }) // off in narrower windows
135
- * @example createGL({ media: "(min-width: 600px)" }) // off on phones
159
+ * Effects only where this CSS media query matches, read when the page loads. Without code: data-umber-media on <body>.
160
+ * @example createUmber({ media: "(min-width: 900px)" }) // off in narrower windows
161
+ * @example createUmber({ media: "(min-width: 600px)" }) // off on phones
136
162
  */
137
163
  media?: string;
138
164
  /**
139
165
  * Device pixel ratio: a max, [min, max], or a max per device tier.
140
166
  * @default { high: 2, mid: 1.5, low: 1 }
141
- * @example createGL({ dpr: [1, 1.5] })
167
+ * @example createUmber({ dpr: [1, 1.5] })
142
168
  */
143
169
  dpr?: number | [number, number] | { high?: number; mid?: number; low?: number };
144
170
  /**
145
171
  * Max canvas pixels (width × height × dpr²); the DPR drops to stay under it.
146
172
  * @default 12e6
147
- * @example createGL({ pixelBudget: 8e6 })
173
+ * @example createUmber({ pixelBudget: 8e6 })
148
174
  */
149
175
  pixelBudget?: number;
150
176
  /**
@@ -164,6 +190,12 @@ export interface GLOptions {
164
190
  * @default true
165
191
  */
166
192
  respectSaveData?: boolean;
193
+ /**
194
+ * Run where WebGL draws on the processor (SwiftShader, llvmpipe, Microsoft Basic Render: no usable GPU), where every
195
+ * frame costs the page its smoothness. Also `data-umber-software` on `<html>` or `<body>`. Off, `umber.reason` is "software".
196
+ * @default false
197
+ */
198
+ software?: boolean;
167
199
  /**
168
200
  * Run inside the Webflow Designer / Editor too (normally the DOM shows there).
169
201
  * @default false
@@ -171,8 +203,8 @@ export interface GLOptions {
171
203
  designer?: boolean;
172
204
  /**
173
205
  * The element the canvas goes in: an element or a selector.
174
- * @default [data-gl-host], or a fixed full-screen host Umber makes as the first child of <body> (next to it when <body> has a zoom)
175
- * @example createGL({ host: ".gl-host" })
206
+ * @default [data-umber-host], or a fixed full-screen host Umber makes as the first child of <body> (next to it when <body> has a zoom)
207
+ * @example createUmber({ host: ".gl-host" })
176
208
  */
177
209
  host?: string | HTMLElement;
178
210
  /**
@@ -187,41 +219,41 @@ export interface GLOptions {
187
219
  zIndex?: number;
188
220
  /**
189
221
  * A selector <html> matches while your router changes the page: meanwhile Umber acts as
190
- * inside gl.transition() (plays held, planes measured every frame, data-gl-id images
222
+ * inside umber.transition() (plays held, planes measured every frame, data-umber-id images
191
223
  * noted), with no hook to write. Off by default (a flag a site forgets to clear would
192
224
  * keep Umber measuring); it ends by itself after 8 s and starts again only once <html>
193
225
  * stopped matching in between.
194
- * @example createGL({ busy: "html.is-changing" }) // Swup
195
- * @example createGL({ busy: 'html[aria-busy="true"]' }) // Turbo
196
- * @example createGL({ busy: "html[data-astro-transition]" }) // Astro's client router
226
+ * @example createUmber({ busy: "html.is-changing" }) // Swup
227
+ * @example createUmber({ busy: 'html[aria-busy="true"]' }) // Turbo
228
+ * @example createUmber({ busy: "html[data-astro-transition]" }) // Astro's client router
197
229
  */
198
230
  busy?: string;
199
231
  /**
200
232
  * The folder the engine's chunks (chunks/gl.js, chunks/shapes.js, chunks/text.js, chunks/layers.js, chunks/morph.js, chunks/video.js, chunks/views.js) load from.
201
233
  * @default the folder umber.js came from (npm: this version's CDN folder, or window.UmberConfig.base)
202
- * @example createGL({ base: "/vendor/umber/" })
234
+ * @example createUmber({ base: "/vendor/umber/" })
203
235
  */
204
236
  base?: string;
205
237
  /**
206
238
  * true: debug notes in the console (also ?umber-debug in the URL). An object also sets
207
239
  * what the debug module shows, once it is loaded (modules/debug.js).
208
240
  * @default false
209
- * @example createGL({ debug: true })
210
- * @example createGL({ modules: [Debug], debug: { outlines: true, markers: true } })
241
+ * @example createUmber({ debug: true })
242
+ * @example createUmber({ modules: [Debug], debug: { outlines: true, markers: true } })
211
243
  */
212
244
  debug?: boolean | DebugOptions;
213
245
  /**
214
246
  * false silences warnings. Errors (a shader that does not compile, a callback that threw)
215
247
  * always show.
216
- * @default true
248
+ * @default true on localhost and with debug on, false on a live site
217
249
  */
218
250
  warnings?: boolean;
219
251
  /**
220
- * Optional modules from the start, as gl.use() would take them.
221
- * @example createGL({ modules: [Scrub] }) // import { Scrub } from "@occluze/umber/scrub"
222
- * @example createGL({ modules: [[Scrub, { cacheMB: 64 }]] })
252
+ * Optional modules from the start, as umber.use() would take them.
253
+ * @example createUmber({ modules: [Scrub] }) // import { Scrub } from "@occluze/umber/scrub"
254
+ * @example createUmber({ modules: [[Scrub, { cacheMB: 64 }]] })
223
255
  */
224
- modules?: Array<UmberModule | [UmberModule, Record<string, unknown>]>;
256
+ modules?: (UmberModule | [UmberModule, Record<string, unknown>])[];
225
257
  }
226
258
 
227
259
  /** What the debug module (modules/debug.js) shows. */
@@ -240,9 +272,11 @@ export interface DebugOptions {
240
272
  * @default false
241
273
  */
242
274
  cost?: boolean;
275
+ /** The frame callbacks' costs against the frame's budget (umber.loop.profile(), chunks/profiler.js). ?umber-debug=profiler. @default false */
276
+ profiler?: boolean;
243
277
  }
244
278
 
245
- /** gl.inspect(el): one plane, and every reason it is not drawn on the visible screen right now. */
279
+ /** umber.inspect(el): one plane, and every reason it is not drawn on the visible screen right now. */
246
280
  export interface InspectReport {
247
281
  el: Element;
248
282
  kind: "image" | "video" | "shader" | "layer" | "text" | "group" | null;
@@ -257,7 +291,7 @@ export interface InspectReport {
257
291
  source?: string;
258
292
  /** The device tier ("high" | "mid" | "low"), plus the scrub tier on scrubbed video. */
259
293
  tier?: string;
260
- effects?: Array<{ name: string; options: Record<string, unknown> }>;
294
+ effects?: { name: string; options: Record<string, unknown> }[];
261
295
  /** used: the compiled shader reads it (null while it compiles). */
262
296
  uniforms?: Record<string, { value: unknown; used: boolean | null }>;
263
297
  program?: { key: string; ready: boolean } | null;
@@ -270,10 +304,15 @@ export interface InspectReport {
270
304
  * Every parent (or the element itself) that cuts it, and how GL draws the cut: "scissor"
271
305
  * (straight: free), "shader" (rounded, shaped or turned: per pixel), "corners" (a rounded
272
306
  * parent hugging the image), "pruned" (cuts nothing), "ignored" (that parent turns past
273
- * the viewer right now). A data-gl-occlude panel over it is `by: "occlude"`; "uncut": it
307
+ * the viewer right now). A data-umber-occlude panel over it is `by: "occlude"`; "uncut": it
274
308
  * overlaps, but no shader slot was free, so GL draws over it there this frame.
275
309
  */
276
- clips?: Array<{ el: Element; by: "overflow" | "clip-path" | "clip" | "occlude"; shape: string; how: "scissor" | "shader" | "corners" | "pruned" | "ignored" | "uncut" }>;
310
+ clips?: {
311
+ el: Element;
312
+ by: "overflow" | "clip-path" | "clip" | "occlude";
313
+ shape: string;
314
+ how: "scissor" | "shader" | "corners" | "pruned" | "ignored" | "uncut";
315
+ }[];
277
316
  /** Where GL draws it (null when it has no plane). */
278
317
  geometry?: {
279
318
  /** "none": flat (translate / scale at most); "2d": rotated, skewed or mirrored; "3d": tilted (perspective). */
@@ -281,32 +320,55 @@ export interface InspectReport {
281
320
  /** uSize: its size on screen (for a turned element: its layout proportions at its on-screen scale). */
282
321
  size: [number, number];
283
322
  /** The drawn quad, viewport px: top-left, top-right, bottom-right, bottom-left of the element's own box. */
284
- corners: Array<[number, number]>;
323
+ corners: [number, number][];
285
324
  /**
286
325
  * What measures it every frame right now, or null: "CSS transition on <div.card>, 0.32 s
287
326
  * left", "infinite CSS animation on <div.track>", "scroll-driven CSS animation on ...",
288
- * "data-gl-live", "a sticky or fixed parent", "live mode (a page change, gl.live())".
327
+ * "data-umber-live", "a sticky or fixed parent", "live mode (a page change, umber.live())".
289
328
  */
290
329
  live: string | null;
291
330
  } | null;
292
331
  }
293
332
 
333
+ /** What a setup callback may return: run when what it set up goes. */
334
+ export type Cleanup = () => void;
335
+
336
+ /**
337
+ * A setup callback: it returns nothing, or `R`, a cleanup (an async setup: a promise of
338
+ * one). Two signatures, so a setup with no return statement is one too.
339
+ */
340
+ export type Setup<C, R = Cleanup> = ((ctx: C) => void) | ((ctx: C) => R);
341
+
342
+ /** The console an add-on prints through, behind the engine's switch (createUmber({ warnings })). */
343
+ export interface ModuleLog {
344
+ warn(...args: unknown[]): void;
345
+ error(...args: unknown[]): void;
346
+ }
347
+
294
348
  /**
295
349
  * An optional Umber module (modules/scrub.js, @occluze/umber/scrub). Elements with
296
- * data-gl-<name> are handed to it; its handle is at plane[name] (gl.plane(el)?.scrub).
297
- * Writing your own is possible but the plane hooks are advanced (see src/types.ts).
350
+ * data-umber-<name> are handed to it; its handle is at plane[name] (umber.plane(el)?.scrub).
351
+ * Writing your own is possible; the plane hooks for that are in types/module.d.ts.
298
352
  */
299
353
  export interface UmberModule {
300
354
  name: string;
301
355
  version?: string;
302
- /** Attributes it owns, without "data-gl-". @default [name] */
356
+ /** Attributes it owns, without "data-umber-". @default [name] */
303
357
  attributes?: string[];
304
- /** `keep(off)` records an undo in the gl.scope() running when it is called, and returns it. `root()`: that scope's container, else document. */
305
- install?(engine: GL, options: Record<string, unknown>, keep: <T>(made: T) => T, root: () => ParentNode): void;
306
- plane?(ctx: any): any;
358
+ /**
359
+ * `keep(off)` records an undo in the umber.scope() running when it is called, and returns it. `root()`: that scope's container, else document.
360
+ * `log`: the console behind the engine's switch (quiet on a live site, createUmber({ warnings })); print through it.
361
+ */
362
+ install?(
363
+ engine: Umber,
364
+ options: Record<string, unknown>,
365
+ keep: <T>(made: T) => T,
366
+ root: () => ParentNode,
367
+ log: ModuleLog,
368
+ ): void;
307
369
  }
308
370
 
309
- export type GLReason =
371
+ export type UmberReason =
310
372
  | "disabled"
311
373
  | "no-webgl2"
312
374
  | "device"
@@ -314,10 +376,12 @@ export type GLReason =
314
376
  | "forced-colors"
315
377
  | "reduced-motion"
316
378
  | "save-data"
379
+ | "software"
317
380
  | "context"
318
381
  | "load-failed"
319
382
  | "load-timeout"
320
383
  | "unlicensed"
384
+ | "licence-unreachable"
321
385
  | "context-lost"
322
386
  | "error"
323
387
  | "server"
@@ -325,6 +389,9 @@ export type GLReason =
325
389
 
326
390
  export type TickPhase = "measure" | "update" | "render";
327
391
 
392
+ export type { FrameOptions, GsapLike, Loop, ProfileLine, Profiler, ProfilerOptions } from "./loop.js";
393
+ import type { FrameOptions, GsapLike, Loop } from "./loop.js";
394
+
328
395
  export interface Frame {
329
396
  /** Seconds since the engine started, lag-smoothed. */
330
397
  time: number;
@@ -337,6 +404,12 @@ export interface Frame {
337
404
  woke: boolean;
338
405
  /** px; velocity in px per second. */
339
406
  scroll: { x: number; y: number; velocity: number };
407
+ /**
408
+ * ms left before this frame takes longer than the screen's frame time: heavy work can
409
+ * skip a frame, or stop and go on in the next one. Live: call it again after some work.
410
+ * @example umber.on("frame", (f) => { while (jobs.length && f.budget() > 2) jobs.shift()!(); });
411
+ */
412
+ budget(): number;
340
413
  }
341
414
 
342
415
  /**
@@ -375,7 +448,7 @@ export type PlaneEvent = "ready" | "enter" | "leave" | "resize" | "error" | "des
375
448
  * One line, word or character of a GL text (plane.text). `t`, `x`, `y`, `z` are four
376
449
  * plain numbers per unit (0 at first) that any library can tween; their meaning is the
377
450
  * effect's. They are kept by index when the text rewraps.
378
- * @example gsap.to(gl.plane(h1).text.lines, { t: 1, stagger: 0.08 })
451
+ * @example gsap.to(umber.plane(h1).text.lines, { t: 1, stagger: 0.08 })
379
452
  */
380
453
  export interface TextUnit {
381
454
  /** 0-based, in reading order: the same numbers as glyph() in GLSL. */
@@ -407,10 +480,10 @@ export interface TextChar extends TextUnit {
407
480
  }
408
481
 
409
482
  /**
410
- * plane.text on data-gl="text" planes (undefined on others, and until chunks/text.js
483
+ * plane.text on data-umber="text" planes (undefined on others, and until chunks/text.js
411
484
  * arrived): its lines, words and characters, empty until the first paint. Where the site
412
485
  * split its own lines ([data-line] elements), those are the lines. The counts also reach
413
- * CSS on the element: var(--gl-lines), var(--gl-words), var(--gl-chars).
486
+ * CSS on the element: var(--umber-lines), var(--umber-words), var(--umber-chars).
414
487
  */
415
488
  export interface PlaneText {
416
489
  readonly lines: TextLine[];
@@ -419,7 +492,7 @@ export interface PlaneText {
419
492
  /** +1 per paint that changed the units. */
420
493
  readonly version: number;
421
494
  /**
422
- * One gl.progress() per line or word (not characters): `start` / `end` written as for
495
+ * One umber.progress() per line or word (not characters): `start` / `end` written as for
423
496
  * the element, measured from each unit's own edges ("top 80%": this line's top at 80 %
424
497
  * of the screen). Make them again after a "text" event.
425
498
  * @example plane.text.progress("lines", { start: "top 85%", end: "top 55%" }).forEach((p, i) => p.on("change", () => (lines[i].t = p.value)))
@@ -427,6 +500,18 @@ export interface PlaneText {
427
500
  progress(level: "lines" | "words", options?: ProgressOptions): ProgressSignal[];
428
501
  }
429
502
 
503
+ /** The indices below each fixed length Umber hands out arrays of. */
504
+ interface Below {
505
+ 4: 0 | 1 | 2 | 3;
506
+ }
507
+
508
+ /**
509
+ * A Float32Array made with N entries, which it keeps: each index below N reads as a
510
+ * number, also under noUncheckedIndexedAccess (plane.rect[2] is a number, not
511
+ * number | undefined).
512
+ */
513
+ export type Float32s<N extends keyof Below> = Float32Array & Record<Below[N], number>;
514
+
430
515
  export interface Plane {
431
516
  readonly id: number;
432
517
  readonly el: HTMLElement;
@@ -434,23 +519,30 @@ export interface Plane {
434
519
  /** "loading" | "ready" | "error" */
435
520
  readonly status: string;
436
521
  /** This frame's viewport rect as [x, y, width, height] (CSS px): rect[2] is the width. */
437
- readonly rect: Float32Array;
438
- /** On screen (the real viewport, like gl.track()); "enter" / "leave" fire as it changes. */
522
+ readonly rect: Float32s<4>;
523
+ /**
524
+ * [x, y] CSS px your code moves the element by this frame with the CSS `translate`
525
+ * property (set it in the measure phase, where the scrollfx module sets its parallax and
526
+ * lag): the plane is drawn that far over in the same frame, and measuring leaves it out, so
527
+ * it needs no measure per frame. null: none.
528
+ */
529
+ offset: [number, number] | null;
530
+ /** On screen (the real viewport, like umber.track()); "enter" / "leave" fire as it changes. */
439
531
  readonly inView: boolean;
440
532
  /** 0 as the element's top enters at the bottom of the screen, 1 as its bottom leaves at the top. */
441
533
  readonly progress: number;
442
- readonly effects: Array<{ name: string; options: Record<string, any> }>;
443
- /** data-gl="text": its lines, words and characters, as data and tweenable numbers. */
534
+ readonly effects: { name: string; options: Record<string, unknown> }[];
535
+ /** data-umber="text": its lines, words and characters, as data and tweenable numbers. */
444
536
  readonly text?: PlaneText;
445
- /** data-gl-instances (or an effect's `instances`): its count and per-instance data. Undefined without. */
537
+ /** data-umber-instances (or an effect's `instances`): its count and per-instance data. Undefined without. */
446
538
  readonly instances?: PlaneInstances;
447
539
  /** Plain { value } objects: animate them with anything. */
448
- readonly uniforms: Record<string, Signal<any>>;
540
+ readonly uniforms: Record<string, Signal<unknown>>;
449
541
  /**
450
- * Set a uniform. A Signal (gl.progress(el), gl.pointer, any { value }) links it: the
542
+ * Set a uniform. A Signal (umber.progress(el), umber.pointer, any { value }) links it: the
451
543
  * uniform follows that Signal from then on. A CSS colour string ("#f30", "oklch(...)",
452
544
  * "var(--brand)") becomes [r, g, b, a] in sRGB (var() read from the element now).
453
- * @example plane.set("uStory", gl.progress(el.closest("section")))
545
+ * @example plane.set("uStory", umber.progress(el.closest("section")))
454
546
  */
455
547
  set(name: string, value: unknown): Plane;
456
548
  get(name: string): unknown;
@@ -470,49 +562,49 @@ export interface Plane {
470
562
  on(event: PlaneEvent, fn: (plane: Plane) => void): () => void;
471
563
  off(event: PlaneEvent, fn: (plane: Plane) => void): void;
472
564
  wake(frames?: number): void;
473
- /** The element shows as normal DOM again. gl.scan(el) brings it back. */
565
+ /** The element shows as normal DOM again. umber.scan(el) brings it back. */
474
566
  destroy(): void;
475
567
  revert(): void;
476
568
  }
477
569
 
478
- /** gl.add(el, options): the attributes it writes, as options (the same contract). */
570
+ /** umber.add(el, options): the attributes it writes, as options (the same contract). */
479
571
  export interface AddOptions {
480
- /** data-gl. @default "image" (or "video" for a <video>) */
572
+ /** data-umber. @default "image" (or "video" for a <video>) */
481
573
  type?: "image" | "video" | "text" | "shader" | "layer" | "group";
482
- /** data-gl-effect: effect names, applied in order. @example effects: ["dissolve"] */
574
+ /** data-umber-effect: effect names, applied in order. @example effects: ["dissolve"] */
483
575
  effects?: string[] | string;
484
- /** data-gl-<effect>-<option>, per effect. @example options: { dissolve: { scale: 6, trigger: "manual" } } */
576
+ /** data-umber-<effect>-<option>, per effect. @example options: { dissolve: { scale: 6, trigger: "manual" } } */
485
577
  options?: Record<string, Record<string, unknown>>;
486
- /** data-gl-shader (with type "shader"). */
578
+ /** data-umber-shader (with type "shader"). */
487
579
  shader?: string;
488
- /** data-gl-layer (with type "layer"). */
580
+ /** data-umber-layer (with type "layer"). */
489
581
  layer?: string;
490
- /** data-gl-src: another image than the <img> inside. */
582
+ /** data-umber-src: another image than the <img> inside. */
491
583
  src?: string;
492
- /** data-gl-fit. */
584
+ /** data-umber-fit. */
493
585
  fit?: "cover" | "contain" | "fill";
494
- /** data-gl-order: draw order. */
586
+ /** data-umber-order: draw order. */
495
587
  order?: number;
496
- /** data-gl-live: measure every frame. */
588
+ /** data-umber-live: measure every frame. */
497
589
  live?: boolean;
498
590
  /**
499
- * data-gl-clip: false draws it without its parents' clips (overflow, clip-path, CSS masks).
591
+ * data-umber-clip: false draws it without its parents' clips (overflow, clip-path, CSS masks).
500
592
  * Its own clip-path still cuts it. @default true
501
593
  */
502
594
  clip?: boolean;
503
- /** data-gl-instances: "64", "tiles 24x16", "chars", "echo 6", "ink 3000". */
595
+ /** data-umber-instances: "64", "tiles 24x16", "chars", "echo 6", "ink 3000", "points 20000". */
504
596
  instances?: string | number;
505
597
  }
506
598
 
507
599
  /**
508
- * plane.instances on a plane drawn as instances (data-gl-instances, or an effect's
600
+ * plane.instances on a plane drawn as instances (data-umber-instances, or an effect's
509
601
  * `instances`): the per-instance numbers of the attributes its effects declare.
510
602
  * @example const seeds = plane.instances.data("aSeed"); seeds[0] = 0.5; plane.instances.update("aSeed");
511
603
  */
512
604
  export interface PlaneInstances {
513
605
  /** How many are drawn (text: its characters, words or lines). */
514
606
  readonly count: number;
515
- readonly mode: "count" | "tiles" | "chars" | "words" | "lines" | "echo" | "ink";
607
+ readonly mode: "count" | "tiles" | "chars" | "words" | "lines" | "echo" | "ink" | "points";
516
608
  /** An attribute's numbers (count x its size), to change in place; then update(name). null when no effect declares it. */
517
609
  data(name: string): Float32Array | null;
518
610
  /** Replace an attribute's numbers (count x its size); sent to the GPU on the next frame. */
@@ -521,13 +613,35 @@ export interface PlaneInstances {
521
613
  update(name?: string): void;
522
614
  }
523
615
 
524
- export interface EffectContext {
616
+ /** A definition's options (umber.effect, umber.shader, umber.layer): each with its default. */
617
+ export type OptionDefaults = Record<string, unknown>;
618
+
619
+ /**
620
+ * One option as an element gives it (data-umber-<name>-<option> > --umber-<name>-<option> > the
621
+ * default), read as its default's type: a number, a boolean or a string; a list default
622
+ * reads an attribute as its words.
623
+ */
624
+ export type OptionValue<T> = T extends number
625
+ ? number
626
+ : T extends boolean
627
+ ? boolean
628
+ : T extends string
629
+ ? string
630
+ : T extends readonly unknown[]
631
+ ? T | string[]
632
+ : T | string;
633
+
634
+ /** A definition's options as one element resolved them (ctx.options). */
635
+ export type ResolvedOptions<O extends OptionDefaults> = { [K in keyof O]: OptionValue<O[K]> };
636
+
637
+ /** `O`: the effect's (or shader's) option defaults, which type ctx.options. */
638
+ export interface EffectContext<O extends OptionDefaults = OptionDefaults> {
525
639
  name: string;
526
640
  el: HTMLElement;
527
641
  plane: Plane;
528
- engine: GL;
529
- options: Record<string, any>;
530
- uniforms: Record<string, Signal<any>>;
642
+ engine: Umber;
643
+ options: ResolvedOptions<O>;
644
+ uniforms: Record<string, Signal<unknown>>;
531
645
  readonly reducedMotion: boolean;
532
646
  viewport: { width: number; height: number };
533
647
  /** Only set during update(). */
@@ -563,7 +677,7 @@ export interface EffectContext {
563
677
  * only: this pixel on screen, viewport CSS px, whatever turns the element),
564
678
  * screenUv() (fragment only: this pixel on screen, 0..1 over the viewport,
565
679
  * y down), uScreen (vec2: the element's centre on the viewport, -1..1, y down)
566
- * #include "name" on a line of its own, in any slot: the gl.chunk() of that name, added
680
+ * #include "name" on a line of its own, in any slot: the umber.chunk() of that name, added
567
681
  * once per program (only included chunks are compiled)
568
682
  * two effects on one plane that declare the same top-level name in their heads (a
569
683
  * function, const, global or #define) each get their own (renamed e<N>_name)
@@ -572,45 +686,46 @@ export interface EffectContext {
572
686
  * after the alpha slot, Umber cuts the plane where its parents cut it in the DOM
573
687
  * (overflow, clip-path); names starting with uUmber / umber are reserved
574
688
  */
575
- export interface EffectDef {
689
+ export interface EffectDef<O extends OptionDefaults = OptionDefaults> {
576
690
  /**
577
691
  * Uniforms it adds, with their first value; Umber writes the GLSL declarations.
578
692
  * number -> float, [x, y(, z, w)] -> vec2..4, 9 numbers -> mat3, 16 -> mat4, a URL
579
693
  * string -> sampler2D (fragment only), and a Signal
580
- * ({ value }: gl.progress(el), gl.pointer, gl.velocity, your own) is followed live. A CSS
694
+ * ({ value }: umber.progress(el), umber.pointer, umber.velocity, your own) is followed live. A CSS
581
695
  * colour string ("#ff3300", "oklch(70% 0.15 30)", "var(--brand)") -> vec4 [r, g, b, a]
582
696
  * in sRGB, converted by the browser (var() read from each element once). Anything
583
- * holding a `texture` (the input module's gl.texture(), gl.touch(), gl.rects()) ->
697
+ * holding a `texture` (the input module's umber.texture(), umber.touch(), umber.rects()) ->
584
698
  * highp sampler2D; a raw canvas, video, a typed array other than Float32Array, or more
585
- * than 896 numbers (more than a phone's uniforms hold) warns: wrap it in gl.texture()
699
+ * than 896 numbers (more than a phone's uniforms hold) warns: wrap it in umber.texture()
586
700
  * (numbers that fit no type above warn only when the GLSL reads them undeclared).
587
701
  * @example uniforms: { uShow: 0, uTint: [1, 0.4, 0.2], uNoise: "/noise.png" }
588
702
  * @example uniforms: { uTint: "var(--brand)" }
589
- * @example uniforms: { uStory: gl.progress(".story"), uPointer: gl.pointer }
703
+ * @example uniforms: { uStory: umber.progress(".story"), uPointer: umber.pointer }
590
704
  */
591
705
  uniforms?: Record<string, unknown>;
592
706
  /**
593
- * Options read per element: data-gl-<effect>-<key> > --gl-<effect>-<key> (CSS) > this
707
+ * Options read per element: data-umber-<effect>-<key> > --umber-<effect>-<key> (CSS) > this
594
708
  * default. Number, boolean, array and CSS colour options become uniforms too: effect
595
709
  * "ripple", option "strength" -> uRippleStrength. Give a colour option a colour default
596
710
  * ({ color: "#fff" }) so every element has the vec4. A string with a "/" is an image
597
- * path -> sampler2D (a per-element map: data-gl-depth-map="/img/a-depth.webp" ->
711
+ * path -> sampler2D (a per-element map: data-umber-depth-map="/img/a-depth.webp" ->
598
712
  * uDepthMap; give it a default path). `bleed` (px) draws the plane that much past its
599
713
  * element on every side (uBleed: the largest of its effects).
714
+ * setup() and update() read them as ctx.options, typed from these defaults.
600
715
  * @example options: { strength: 1, duration: 1.2, ease: "expo.out" }
601
716
  * @example options: { map: "/img/blank.webp", bleed: 40 }
602
717
  */
603
- options?: Record<string, unknown>;
718
+ options?: O;
604
719
  /**
605
720
  * Uniform values used instead when the visitor prefers reduced motion (and
606
- * createGL({ reducedMotion }) is "static", the default): keep a fade, still a wave.
721
+ * createUmber({ reducedMotion }) is "static", the default): keep a fade, still a wave.
607
722
  * @example reduced: { uWave: 0 }
608
723
  */
609
724
  reduced?: Record<string, unknown>;
610
725
  /**
611
726
  * A uniform Umber plays 0 -> 1 by itself, with the trigger options every playable
612
727
  * effect understands: trigger (auto | scroll | load | manual | hover), delay, duration, ease,
613
- * start ("top 90%").
728
+ * start ("top 90%"), repeat ("" once | "reverse" | "true": again each time it scrolls in).
614
729
  * @example play: "uShow"
615
730
  */
616
731
  play?: string;
@@ -621,7 +736,7 @@ export interface EffectDef {
621
736
  segments?: number;
622
737
  /**
623
738
  * Draw the plane many times in ONE draw call (chunks/instances.js). The element's own
624
- * data-gl-instances wins. GLSL then has `instance` (0..uInstances - 1) and `uInstances`,
739
+ * data-umber-instances wins. GLSL then has `instance` (0..uInstances - 1) and `uInstances`,
625
740
  * plus per mode:
626
741
  * "64" (or { count: 64 }) copies: place each with `instance` in vertex.main
627
742
  * "tiles 24x16" one quad per tile: `tile` (vec4 column, row, columns, rows),
@@ -634,10 +749,26 @@ export interface EffectDef {
634
749
  * "ink 3000" ("size 3", "luma") 3000 particles seeded where the plane has ink (alpha, or
635
750
  * brightness), each a `size` px piece of the plane:
636
751
  * `inkPoint` (vec4: uv, ink 0..1, found)
752
+ * "points 20000" ("size 3") 20000 particles spread evenly at random over the plane, placed
753
+ * on the GPU (no seed pass): `point` (vec4: uv, two random
754
+ * numbers 0..1), `pointUv` (vec2: 0..1 across the particle)
637
755
  * Every input is there in vertex and fragment code; your attributes in vertex code only.
638
756
  * @example instances: "tiles 16x10", vertex: { main: "pos.xy += (tileCenter - 0.5) * uSize * uSpread;" }
639
757
  */
640
- instances?: number | string | { count?: number; tiles?: string | [number, number]; units?: "chars" | "words" | "lines"; echo?: number; delay?: number; ink?: number; size?: number; source?: "alpha" | "luma" };
758
+ instances?:
759
+ | number
760
+ | string
761
+ | {
762
+ count?: number;
763
+ tiles?: string | [number, number];
764
+ units?: "chars" | "words" | "lines";
765
+ echo?: number;
766
+ delay?: number;
767
+ ink?: number;
768
+ points?: number;
769
+ size?: number;
770
+ source?: "alpha" | "luma";
771
+ };
641
772
  /**
642
773
  * Per-instance numbers, as `in` attributes of the vertex shader (declared for you): a size
643
774
  * (1-4: a stable random 0..1 per instance and component) or a function of the instance
@@ -651,32 +782,33 @@ export interface EffectDef {
651
782
  * fragment.uv changes `uv` before the image is sampled; color changes `color` (vec4);
652
783
  * alpha changes `alpha` (float, already the element's opacity and corners: multiply it).
653
784
  * head holds functions and globals shared between slots, and #include "name" lines
654
- * (gl.chunk()).
785
+ * (umber.chunk()).
655
786
  * Helpers: sampleImage(uv), sampleRaw(uv), roundedBox(p, size, vec4 radii), noise(vec2 | vec3), fbm(vec2),
656
787
  * rotate2d(a), umberHash(vec2 | vec3), screenPx(), screenUv().
657
788
  * @example fragment: { color: "color.rgb *= uTint;" }
658
789
  */
659
790
  fragment?: { head?: string; uv?: string; color?: string; alpha?: string };
660
- /** Once per plane. Return a cleanup (also: ctx.listen() cleans up by itself). */
661
- setup?: (ctx: EffectContext) => void | (() => void);
791
+ /** Once per plane. Return a cleanup (also: ctx.listen() cleans up by itself), or nothing. */
792
+ setup?: Setup<EffectContext<O>>;
662
793
  /** Every drawn frame while the plane is on screen (ctx.frame is set). */
663
- update?: (ctx: EffectContext) => void;
794
+ update?(ctx: EffectContext<O>): void;
664
795
  }
665
796
 
666
- export interface ShaderDef {
797
+ export interface ShaderDef<O extends OptionDefaults = OptionDefaults> {
667
798
  /** Set `color` (vec4) from `uv`. */
668
799
  fragment: string;
669
800
  head?: string;
670
801
  uniforms?: Record<string, unknown>;
671
802
  /**
672
- * Options read per element: data-gl-shader-<key> > --gl-shader-<key> > this default.
803
+ * Options read per element: data-umber-shader-<key> > --umber-shader-<key> > this default.
673
804
  * Number, boolean and array options become uniforms named u + Option (speed -> uSpeed).
674
805
  */
675
- options?: Record<string, unknown>;
806
+ options?: O;
676
807
  /** Keep drawing every frame while visible (not under reduced motion with reducedMotion "static": uTime stands still). @default true */
677
808
  animate?: boolean;
678
- setup?: (ctx: EffectContext) => void | (() => void);
679
- update?: (ctx: EffectContext) => void;
809
+ /** Once per element. Return a cleanup, or nothing. */
810
+ setup?: Setup<EffectContext<O>>;
811
+ update?(ctx: EffectContext<O>): void;
680
812
  }
681
813
 
682
814
  export interface LayerRect {
@@ -686,14 +818,25 @@ export interface LayerRect {
686
818
  height: number;
687
819
  }
688
820
 
689
- export interface LayerContext {
821
+ /** What ctx.three() sets on a THREE.WebGLRenderer (a method it lacks is skipped). */
822
+ export interface LayerRendererLike {
823
+ autoClear: boolean;
824
+ resetState?(): void;
825
+ setViewport?(x: number, y: number, width: number, height: number): void;
826
+ setScissor?(x: number, y: number, width: number, height: number): void;
827
+ setScissorTest?(on: boolean): void;
828
+ }
829
+
830
+ /** `O`: the layer's option defaults (ctx.options). `S`: what you keep in ctx.state: umber.layer<O, S>(name, def). */
831
+ export interface LayerContext<O extends OptionDefaults = OptionDefaults, S extends object = Record<string, unknown>> {
690
832
  name: string;
691
833
  el: HTMLElement;
692
834
  gl: WebGL2RenderingContext;
693
835
  canvas: HTMLCanvasElement;
694
- options: Record<string, any>;
695
- state: Record<string, any>;
696
- engine: GL;
836
+ options: ResolvedOptions<O>;
837
+ /** Your own storage for this element's layer (renderer, scene, meshes...): empty when setup() starts, filled by it. */
838
+ state: S;
839
+ engine: Umber;
697
840
  rect: LayerRect;
698
841
  px: LayerRect;
699
842
  viewport: { width: number; height: number };
@@ -707,18 +850,22 @@ export interface LayerContext {
707
850
  /** Draw at least `frames` more frames. Under reduced motion ("static") an animating layer draws only on this (and when setup() resolves): call it when a model loaded after setup lands. */
708
851
  wake(frames?: number): void;
709
852
  busy(on: boolean): void;
710
- three(renderer: any): void;
853
+ /** three.js: resetState, autoClear off, viewport + scissor to this element. */
854
+ three(renderer: LayerRendererLike): void;
711
855
  }
712
856
 
713
- export interface LayerDef {
714
- /** Read per element into ctx.options: data-gl-layer-<key> > --gl-layer-<key> > this default. */
715
- options?: Record<string, unknown>;
716
- /** Once, when the element comes near the screen. May be async; return a cleanup. */
717
- setup?: (ctx: LayerContext) => void | (() => void) | Promise<void | (() => void)>;
857
+ export interface LayerDef<O extends OptionDefaults = OptionDefaults, S extends object = Record<string, unknown>> {
858
+ /** Read per element into ctx.options: data-umber-layer-<key> > --umber-layer-<key> > this default. */
859
+ options?: O;
860
+ /**
861
+ * Once, when the element comes near the screen; render() and resize() wait for it. May be
862
+ * async; return (or resolve to) a cleanup, or nothing. ctx.state starts empty: fill it here.
863
+ */
864
+ setup?: Setup<LayerContext<O, Partial<S>>, Cleanup | Promise<Cleanup | undefined>>;
718
865
  /** Draw (ctx.three(renderer) first for three.js). */
719
- render: (ctx: LayerContext) => void;
866
+ render(ctx: LayerContext<O, S>): void;
720
867
  /** The element or the screen changed size (before render). */
721
- resize?: (ctx: LayerContext) => void;
868
+ resize?(ctx: LayerContext<O, S>): void;
722
869
  /** Draw every frame while visible (not under reduced motion with reducedMotion "static": ctx.time stands still, and it draws on ctx.wake()). false: only on wake(), busy(true), resize and scroll. @default true */
723
870
  animate?: boolean;
724
871
  /** Clip drawing to the element box. @default true */
@@ -727,12 +874,14 @@ export interface LayerDef {
727
874
  followOpacity?: boolean;
728
875
  /** Max device px per CSS px for this layer (a heavy scene renders smaller, upscaled). @default the canvas's */
729
876
  dpr?: number;
877
+ /**
878
+ * Under the page's passes (data-umber-pass on <body>), like Umber's own planes: drawn alone, copied, and the copy
879
+ * drawn in its place (one copy of its box per frame while the page has passes). false: straight to the canvas,
880
+ * under the passes. @default false (data-umber="model" and the three module's scenes: true)
881
+ */
882
+ passes?: boolean;
730
883
  }
731
884
 
732
- // -----------------------------------------
733
- // Tracking, three.js views and DOM <-> world maths
734
- // -----------------------------------------
735
-
736
885
  export interface TrackRect {
737
886
  x: number;
738
887
  y: number;
@@ -747,7 +896,7 @@ export interface TrackOptions {
747
896
  live?: boolean;
748
897
  }
749
898
 
750
- /** gl.track(el): where an element is, every frame, without layout reads or WebGL. */
899
+ /** umber.track(el): where an element is, every frame, without layout reads or WebGL. */
751
900
  export interface Tracker {
752
901
  readonly el: Element;
753
902
  /** Viewport CSS px this frame (y down), like getBoundingClientRect. */
@@ -779,15 +928,17 @@ export interface ProgressOptions {
779
928
  /**
780
929
  * Also write the value (4 decimals, only when it changed) to this CSS custom property on
781
930
  * the element, through a rule of Umber's own stylesheet (not its style attribute).
782
- * @example gl.progress(".hero", { css: "--hero" }) // .hero img { opacity: calc(1 - var(--hero)) }
931
+ * @example umber.progress(".hero", { css: "--hero" }) // .hero img { opacity: calc(1 - var(--hero)) }
783
932
  */
784
933
  css?: string;
785
934
  /** Measure every frame (a parent moved by transforms). @default auto (sticky, fixed or pinned parents) */
786
935
  live?: boolean;
936
+ /** "x": along the screen's width, for a page that scrolls sideways (edges: left / right, or top / bottom read as them). @default "y" */
937
+ axis?: "x" | "y";
787
938
  }
788
939
 
789
- /** gl.progress(el): a live 0..1 as el scrolls from `start` to `end`. Usable as a uniform. */
790
- export interface ProgressSignal extends Signal<number> {
940
+ /** umber.progress(el): a live 0..1 as el scrolls from `start` to `end`. Usable as a uniform. */
941
+ export interface ProgressSignal extends Signal {
791
942
  readonly el: Element;
792
943
  readonly start: string;
793
944
  readonly end: string;
@@ -800,9 +951,9 @@ export interface ProgressSignal extends Signal<number> {
800
951
  }
801
952
 
802
953
  /**
803
- * gl.pointer: the pointer (mouse, pen or touch). Usable as a uniform (vec2).
804
- * More inputs (gl.drag, gl.velocityOf any Signal, gl.trail, gl.press, gl.step) come with
805
- * the input module: gl.use(Input) from "@occluze/umber/input" (types/input.d.ts).
954
+ * umber.pointer: the pointer (mouse, pen or touch). Usable as a uniform (vec2).
955
+ * More inputs (umber.drag, umber.velocityOf any Signal, umber.trail, umber.press, umber.step) come with
956
+ * the input module: umber.use(Input) from "@occluze/umber/input" (types/input.d.ts).
806
957
  */
807
958
  export interface PointerSignal {
808
959
  /** [x, y] in viewport CSS px (y down). The viewport's centre until the pointer first moves. */
@@ -813,11 +964,22 @@ export interface PointerSignal {
813
964
  readonly active: boolean;
814
965
  }
815
966
 
967
+ /** What a scope makes with gl's own calls (s.add...), and the definitions and other calls it carries as they are. */
968
+ type ScopeMakes = "add" | "track" | "progress" | "attach" | "view" | "target" | "snapshot" | "sim" | "flow" | "brush";
969
+ type ScopeCarries =
970
+ "effect" | "shader" | "layer" | "chunk" | "on" | "nextFrame" | "scope" | "preload" | "warm" | "leave" | "flip";
971
+
816
972
  /**
817
- * gl.scope(fn, container): everything Umber made inside fn, undone with revert(). The
973
+ * umber.scope(fn, container): everything Umber made inside fn, undone with revert(). The
818
974
  * scope has gl's creating methods: after an await, call them on the scope (s.add, s.track...).
975
+ * An add-on's methods join them (types/input.d.ts: s.drag, s.texture...). On revert():
976
+ * targets, snapshots, sims and brushes are released (the shared umber.flow() flowmap only when
977
+ * this scope's call made it and no plane reads uFlow; options a scope set on it stay);
978
+ * umber.preload({ hover }) is turned off (what it fetched is freed unclaimed after 20 s); this
979
+ * scope's umber.leave() comes out, and the newest one left (or none) is on again, once a page
980
+ * change that holds or plays it ends.
819
981
  */
820
- export interface Scope {
982
+ export interface Scope extends Pick<Umber, ScopeMakes | ScopeCarries> {
821
983
  /** Where selector strings resolve inside the scope (null: the document). */
822
984
  readonly container: Element | null;
823
985
  readonly reverted: boolean;
@@ -828,61 +990,50 @@ export interface Scope {
828
990
  /** Destroy everything made in the scope, newest first; previous definitions come back. */
829
991
  revert(): void;
830
992
  destroy(): void;
831
- add(el: string | Element, options?: AddOptions): Promise<Plane | null>;
832
- track(el: string | Element, options?: TrackOptions): Tracker;
833
- progress(el: string | Element, options?: ProgressOptions): ProgressSignal;
834
- attach(el: string | Element, options: AttachOptions): View;
835
- view(el: string | Element, options?: SharedViewOptions): View;
836
- effect(name: string, def: EffectDef): void;
837
- shader(name: string, def: ShaderDef): void;
838
- layer(name: string, def: LayerDef): void;
839
- chunk(name: string, glsl: string): void;
840
- on(name: "frame", fn: (frame: Frame) => void, opts?: { phase?: TickPhase; order?: number; always?: boolean }): () => void;
841
- on(name: "ready" | "lost" | "restored" | "destroy", fn: (payload?: any) => void): () => void;
842
- /** The roots of the subtrees that entered the page (a router's new page), once per frame; <html> on the first scan. */
843
- on(name: "added", fn: (roots: Element[]) => void): () => void;
844
- /**
845
- * GL is off for this visit, from the start (a device it skips, ?umber=off) or later (a new
846
- * page with data-gl-disable): `reason` is gl.reason. Also on document as "umber:off". For
847
- * the site's own analytics.
848
- */
849
- on(name: "off", fn: (e: { reason: GLReason }) => void): () => void;
850
- /**
851
- * A plane shows its DOM instead of GL: `reason` is the warning's words (what GL can't draw,
852
- * or GL text that stays DOM text), or null when something failed (a picture or video that
853
- * could not load, a shader that did not compile: the console says why). Also on document
854
- * as "umber:fallback".
855
- */
856
- on(name: "fallback", fn: (e: { el: Element; reason: string | null }) => void): () => void;
857
- nextFrame(fn: (frame: Frame) => void, opts?: { phase?: TickPhase; order?: number }): () => void;
858
- scope(fn?: (scope: Scope) => unknown, container?: string | Element | null): Scope;
859
- /** Released on revert() (the shared gl.flow() flowmap only when this scope's call made it and no plane reads uFlow; options a scope set on it stay). */
860
- target: GL["target"];
861
- snapshot: GL["snapshot"];
862
- sim: GL["sim"];
863
- flow: GL["flow"];
864
- brush: GL["brush"];
865
- /** gl.preload({ hover }) is turned off on revert(); what it fetched is freed unclaimed after 20 s. */
866
- preload: GL["preload"];
867
- warm: GL["warm"];
868
- /** revert() takes this scope's gl.leave() out: the newest one left (or none) is on again, once a page change that holds or plays it ends. */
869
- leave: GL["leave"];
870
- flip: GL["flip"];
871
- }
872
-
873
- /** What Umber calls on a THREE.WebGLRenderer (Umber never imports three.js). */
993
+ }
994
+
995
+ /**
996
+ * What Umber calls on the THREE.WebGLRenderer you hand umber.attach() (Umber never imports
997
+ * three.js): your renderer's own type flows through to the view's callbacks.
998
+ */
874
999
  export interface ThreeRendererLike {
875
1000
  domElement?: HTMLCanvasElement;
876
1001
  setSize?(width: number, height: number, updateStyle?: boolean): void;
877
1002
  setPixelRatio?(ratio: number): void;
878
- render?(scene: any, camera: any): void;
1003
+ /** The default render(): renderer.render(scene, camera), with the scene and camera you passed. */
1004
+ render?(scene: unknown, camera: unknown): void;
879
1005
  getContext?(): WebGLRenderingContext | WebGL2RenderingContext;
880
1006
  dispose?(): void;
881
- [key: string]: any;
882
1007
  }
883
1008
 
884
- /** The object a view's animate / render / resize get. */
885
- export interface ViewFrame {
1009
+ /** What Umber sets and calls on the one renderer umber.renderer(THREE) makes on its canvas. */
1010
+ export interface SharedRendererLike
1011
+ extends LayerRendererLike, Pick<ThreeRendererLike, "setPixelRatio" | "setSize" | "dispose"> {
1012
+ /** The default render(): renderer.render(scene, camera), with the view's scene and camera. */
1013
+ render(scene: unknown, camera: unknown): void;
1014
+ }
1015
+
1016
+ /** What umber.renderer(THREE) needs of the three.js module: its WebGLRenderer, made on Umber's canvas and context. */
1017
+ export interface ThreeModuleLike<R extends SharedRendererLike> {
1018
+ WebGLRenderer: new (params: { canvas: HTMLCanvasElement; context: WebGL2RenderingContext }) => R;
1019
+ }
1020
+
1021
+ /**
1022
+ * A view's camera: what Umber reads of it. A PerspectiveCamera's aspect follows the box
1023
+ * (isPerspectiveCamera, aspect, updateProjectionMatrix), and view.rectToWorld() /
1024
+ * view.worldToRect() map with its matrices (they throw without a camera).
1025
+ */
1026
+ export type ViewCameraLike = Partial<CameraLike>;
1027
+
1028
+ /**
1029
+ * The object a view's animate / render / resize get. `S`, `C`, `R`: your scene, camera
1030
+ * and renderer types, from the options you passed.
1031
+ */
1032
+ export interface ViewFrame<
1033
+ S = unknown,
1034
+ C extends ViewCameraLike | undefined = ViewCameraLike | undefined,
1035
+ R = unknown,
1036
+ > {
886
1037
  time: number;
887
1038
  dt: number;
888
1039
  ratio: number;
@@ -898,31 +1049,40 @@ export interface ViewFrame {
898
1049
  velocity: number;
899
1050
  /** prefers-reduced-motion: animate() still runs, but returning true no longer loops. */
900
1051
  reducedMotion: boolean;
901
- renderer: any;
902
- scene: any;
903
- camera: any;
1052
+ renderer: R;
1053
+ scene: S;
1054
+ camera: C;
904
1055
  view: View;
905
1056
  }
906
1057
 
907
- export interface ViewSetupContext {
1058
+ export interface ViewSetupContext<
1059
+ S = unknown,
1060
+ C extends ViewCameraLike | undefined = ViewCameraLike | undefined,
1061
+ R = unknown,
1062
+ > {
908
1063
  el: HTMLElement;
909
- renderer: any;
910
- scene: any;
911
- camera: any;
1064
+ renderer: R;
1065
+ scene: S;
1066
+ camera: C;
912
1067
  view: View;
913
1068
  }
914
1069
 
915
- export interface ViewOptions {
916
- scene?: any;
917
- camera?: any;
1070
+ /** `S`, `C`, `R`: the scene, camera and renderer the callbacks get (umber.view(): the shared renderer, null until umber.renderer() resolved). */
1071
+ export interface ViewOptions<
1072
+ S = unknown,
1073
+ C extends ViewCameraLike | undefined = ViewCameraLike | undefined,
1074
+ R = unknown,
1075
+ > {
1076
+ scene?: S;
1077
+ camera?: C;
918
1078
  /** Draw yourself. @default renderer.render(scene, camera) */
919
- render?: (f: ViewFrame) => void;
920
- /** Before every drawn frame. Return true to draw the next frame too. */
921
- animate?: (f: ViewFrame) => boolean | void;
922
- /** Once, when the element comes near the screen. May be async (compileAsync) and return a cleanup. */
923
- setup?: (ctx: ViewSetupContext) => void | (() => void) | Promise<void | (() => void)>;
1079
+ render?: (f: ViewFrame<S, C, R>) => void;
1080
+ /** Before every drawn frame. Return true to draw the next frame too; anything else draws again only on wake(), busy() or a resize. */
1081
+ animate?: (f: ViewFrame<S, C, R>) => boolean | undefined;
1082
+ /** Once, when the element comes near the screen. May be async (compileAsync); return (or resolve to) a cleanup, or nothing. */
1083
+ setup?: Setup<ViewSetupContext<S, C, R>, Cleanup | Promise<Cleanup | undefined>>;
924
1084
  /** After Umber sized the drawing (a PerspectiveCamera's aspect is already set). */
925
- resize?: (f: ViewFrame) => void;
1085
+ resize?: (f: ViewFrame<S, C, R>) => void;
926
1086
  /** Devices this view runs on, instead of the engine's. @example "all" (phones on for this scene only) */
927
1087
  devices?: "all" | "desktop" | false | ((env: Env) => boolean);
928
1088
  /** A max DPR or [min, max] for this view. @default the engine's dpr */
@@ -931,9 +1091,13 @@ export interface ViewOptions {
931
1091
  aspect?: boolean;
932
1092
  }
933
1093
 
934
- export interface AttachOptions extends ViewOptions {
1094
+ export interface AttachOptions<
1095
+ S = unknown,
1096
+ C extends ViewCameraLike | undefined = ViewCameraLike | undefined,
1097
+ R extends ThreeRendererLike = ThreeRendererLike,
1098
+ > extends ViewOptions<S, C, R> {
935
1099
  /** Your THREE.WebGLRenderer. Its canvas goes into the element unless it is in the page already. */
936
- renderer: ThreeRendererLike;
1100
+ renderer: R;
937
1101
  /** Max drawing pixels (w * h * dpr^2). @default the engine's pixelBudget, else 12e6 */
938
1102
  pixelBudget?: number;
939
1103
  /** Lower the resolution only when frames get slow. @default the engine's adaptive */
@@ -942,17 +1106,24 @@ export interface AttachOptions extends ViewOptions {
942
1106
  dispose?: boolean;
943
1107
  }
944
1108
 
945
- export interface SharedViewOptions extends ViewOptions {
1109
+ /** `R`: the renderer umber.renderer(THREE) made (null in the callbacks until it resolved). */
1110
+ export interface SharedViewOptions<
1111
+ S = unknown,
1112
+ C extends ViewCameraLike | undefined = ViewCameraLike | undefined,
1113
+ R extends SharedRendererLike = SharedRendererLike,
1114
+ > extends ViewOptions<S, C, R | null> {
946
1115
  /** Fade with the element's (and its parents') opacity. @default true */
947
1116
  followOpacity?: boolean;
948
1117
  /** Clip drawing to the element box. @default true */
949
1118
  scissor?: boolean;
1119
+ /** Under the page's passes (data-umber-pass), like Umber's own planes (see LayerDef.passes). @default false */
1120
+ passes?: boolean;
950
1121
  }
951
1122
 
952
1123
  export type ViewStatus = "loading" | "ready" | "off" | "error" | "lost" | "destroyed";
953
1124
  export type ViewEvent = "ready" | "resize" | "enter" | "leave" | "lost" | "restored" | "error" | "destroy";
954
1125
 
955
- /** gl.attach() / gl.view(): your three.js scene tied to an element. */
1126
+ /** umber.attach() / umber.view(): your three.js scene tied to an element. */
956
1127
  export interface View {
957
1128
  readonly el: HTMLElement;
958
1129
  readonly kind: "attach" | "view";
@@ -1046,7 +1217,12 @@ export interface UmberMath {
1046
1217
  /** Aim the camera so it sees exactly `size` at z = 0, `unit` CSS px per world unit (default 1). */
1047
1218
  fitCamera<C extends CameraLike>(camera: C, size: { width: number; height: number }, unit?: number): C;
1048
1219
  /** A DOM rect's centre on the plane z (default 0) and its size there; writes x, y, z into `out`. */
1049
- rectToWorld(rect: RectLike, camera: CameraLike, out?: Partial<Vec3Like> | null, options?: { z?: number; frame?: RectLike }): WorldBox;
1220
+ rectToWorld(
1221
+ rect: RectLike,
1222
+ camera: CameraLike,
1223
+ out?: Partial<Vec3Like> | null,
1224
+ options?: { z?: number; frame?: RectLike },
1225
+ ): WorldBox;
1050
1226
  /** A world point in viewport CSS px. */
1051
1227
  worldToRect(point: Vec3Like, camera: CameraLike, frame?: RectLike): ScreenPoint;
1052
1228
  /** Lerp that feels the same at 60, 120 and 144 Hz: damp(current, target, 0.1, f.dt). */
@@ -1057,125 +1233,152 @@ export interface UmberMath {
1057
1233
  /** GLSL's smoothstep: 0 below edge0, 1 above edge1, smooth between. */
1058
1234
  smoothstep(edge0: number, edge1: number, x: number): number;
1059
1235
  /**
1060
- * 0..1 as a rect scrolls from start to end, written like gl.progress().
1236
+ * 0..1 as a rect scrolls from start to end, written like umber.progress().
1061
1237
  * @example rectProgress(el.getBoundingClientRect(), "top bottom", "bottom top")
1062
1238
  */
1063
- rectProgress(rect: { top?: number; y?: number; height: number }, start?: string, end?: string, viewportHeight?: number): number;
1239
+ rectProgress(
1240
+ rect: { top?: number; y?: number; height: number },
1241
+ start?: string,
1242
+ end?: string,
1243
+ viewportHeight?: number,
1244
+ ): number;
1064
1245
  }
1065
1246
 
1066
- /** What createGL() returns. */
1067
- export interface GL {
1247
+ /** umber.on(name, fn): what each event hands fn. Each but "frame" also goes to document as a DOM event, "umber:<name>" (payload in detail). */
1248
+ export interface UmberEvents {
1249
+ /** Every frame the loop runs (umber.on("frame") adds fn to the loop). */
1250
+ frame: Frame;
1251
+ /** GL draws this page's [data-umber] elements: the engine. */
1252
+ ready: Umber;
1253
+ /** The WebGL context was lost. */
1254
+ lost: undefined;
1255
+ /** The WebGL context is back. */
1256
+ restored: undefined;
1257
+ /** umber.destroy(): the engine is gone. */
1258
+ destroy: undefined;
1259
+ /** The roots of the subtrees that entered the page (a router's new page), once per frame; <html> on the first scan. */
1260
+ added: Element[];
1261
+ /**
1262
+ * GL is off for this visit, from the start (a device it skips, ?umber=off) or later (a new
1263
+ * page with data-umber-disable): `reason` is umber.reason. For the site's own analytics.
1264
+ */
1265
+ off: { reason: UmberReason };
1266
+ /**
1267
+ * A plane shows its DOM instead of GL: `reason` is the warning's words (what GL can't draw,
1268
+ * or GL text that stays DOM text), or null when something failed (a picture or video that
1269
+ * could not load, a shader that did not compile: the console says why).
1270
+ */
1271
+ fallback: { el: Element; reason: string | null };
1272
+ }
1273
+
1274
+ /** What createUmber() returns. */
1275
+ export interface Umber {
1068
1276
  readonly version: string;
1069
- /** true once GL draws this page's [data-gl] elements; false when GL is off or the page has none. */
1277
+ /** true once GL draws this page's [data-umber] elements; false when GL is off or the page has none. */
1070
1278
  readonly ready: Promise<boolean>;
1071
1279
  readonly enabled: boolean;
1072
- readonly reason: GLReason | null;
1280
+ readonly reason: UmberReason | null;
1073
1281
  readonly destroyed: boolean;
1074
1282
  /** Smoothed scroll velocity, roughly -1..1. */
1075
1283
  readonly velocity: Signal;
1076
1284
  /**
1077
1285
  * The pointer: { value: [x, y] } viewport px, velocity.value [vx, vy] px/s. Its passive
1078
1286
  * listeners attach the first time it is read. Usable as a uniform.
1079
- * @example gl.effect("lens", { uniforms: { uPointer: gl.pointer }, fragment: { ... } })
1287
+ * @example umber.effect("lens", { uniforms: { uPointer: umber.pointer }, fragment: { ... } })
1080
1288
  */
1081
1289
  readonly pointer: PointerSignal;
1082
1290
  /**
1083
- * "ready" | "lost" | "restored" | "destroy", or "frame" (adds fn to the loop). Returns off().
1291
+ * An event (UmberEvents says what fn gets), or "frame": fn joins the loop. Returns off().
1084
1292
  * A "frame" callback keeps the loop running every frame; { always: false } only rides
1085
- * along on frames Umber runs anyway. The four state events are also sent on document as
1086
- * DOM events (umber:ready, umber:lost, umber:restored, umber:destroy; payload in detail).
1087
- * @example const off = gl.on("frame", (f) => { mesh.rotation.y += f.dt; }, { phase: "update" });
1293
+ * along on frames Umber runs anyway. The other events are also sent on document as DOM
1294
+ * events (umber:ready, umber:off...; payload in detail).
1295
+ * @example const off = umber.on("frame", (f) => { mesh.rotation.y += f.dt; }, { phase: "update" });
1296
+ * @example umber.on("fallback", ({ el, reason }) => analytics.track("umber-fallback", { reason }));
1088
1297
  * @example document.addEventListener("umber:ready", (e) => console.log(e.detail));
1089
1298
  */
1090
- on(name: "frame", fn: (frame: Frame) => void, opts?: { phase?: TickPhase; order?: number; always?: boolean }): () => void;
1091
- on(name: "ready" | "lost" | "restored" | "destroy", fn: (payload?: any) => void): () => void;
1092
- /** The roots of the subtrees that entered the page (a router's new page), once per frame; <html> on the first scan. */
1093
- on(name: "added", fn: (roots: Element[]) => void): () => void;
1094
- /**
1095
- * GL is off for this visit, from the start (a device it skips, ?umber=off) or later (a new
1096
- * page with data-gl-disable): `reason` is gl.reason. Also on document as "umber:off". For
1097
- * the site's own analytics.
1098
- */
1099
- on(name: "off", fn: (e: { reason: GLReason }) => void): () => void;
1100
- /**
1101
- * A plane shows its DOM instead of GL: `reason` is the warning's words (what GL can't draw,
1102
- * or GL text that stays DOM text), or null when something failed (a picture or video that
1103
- * could not load, a shader that did not compile: the console says why). Also on document
1104
- * as "umber:fallback".
1105
- */
1106
- on(name: "fallback", fn: (e: { el: Element; reason: string | null }) => void): () => void;
1107
- off(name: string, fn: (payload?: any) => void): void;
1108
- effect(name: string, def: EffectDef): void;
1109
- shader(name: string, def: ShaderDef): void;
1110
- layer(name: string, def: LayerDef): void;
1299
+ on(name: "frame", fn: (frame: Frame) => void, opts?: FrameOptions): () => void;
1300
+ on<E extends keyof UmberEvents>(name: E, fn: (payload: UmberEvents[E]) => void): () => void;
1301
+ off<E extends keyof UmberEvents>(name: E, fn: (payload: UmberEvents[E]) => void): void;
1302
+ /** `O`: the option defaults, which type ctx.options in setup() and update(). */
1303
+ effect<O extends OptionDefaults>(name: string, def: EffectDef<O>): void;
1304
+ shader<O extends OptionDefaults>(name: string, def: ShaderDef<O>): void;
1305
+ /** `S`: what the layer keeps in ctx.state: umber.layer<{ speed: number }, { scene: THREE.Scene }>("discs", { ... }). */
1306
+ layer<O extends OptionDefaults, S extends object = Record<string, unknown>>(name: string, def: LayerDef<O, S>): void;
1111
1307
  /**
1112
1308
  * A named piece of GLSL an effect pulls in with a line of its own in any slot:
1113
1309
  * #include "name". Only included chunks are compiled, once per program, after Umber's
1114
1310
  * helpers and before the effects' heads; a chunk may include others (added first) and is
1115
1311
  * never renamed. Defined again: the planes using it are rebuilt. An element whose effect
1116
1312
  * includes an unknown name shows its DOM (one [umber] warning) until it is defined.
1117
- * @example gl.chunk("sdf", "float sdCircle(vec2 p, float r) { return length(p) - r; }")
1118
- * @example gl.effect("ring", { fragment: { head: '#include "sdf"', alpha: "alpha *= step(sdCircle(uv - 0.5, 0.4), 0.0);" } })
1313
+ * @example umber.chunk("sdf", "float sdCircle(vec2 p, float r) { return length(p) - r; }")
1314
+ * @example umber.effect("ring", { fragment: { head: '#include "sdf"', alpha: "alpha *= step(sdCircle(uv - 0.5, 0.4), 0.0);" } })
1119
1315
  */
1120
1316
  chunk(name: string, glsl: string): void;
1121
1317
  /**
1122
1318
  * Use an optional module (before or after GL loads). A module script does this itself.
1123
- * @example gl.use(Scrub, { cacheMB: 128 })
1319
+ * @example umber.use(Scrub, { cacheMB: 128 })
1124
1320
  */
1125
- use(module: UmberModule, options?: Record<string, unknown>): GL;
1321
+ use(module: UmberModule, options?: Record<string, unknown>): Umber;
1126
1322
  /**
1127
1323
  * Whether this page's domain is on an Umber licence (the domains listed at occluze.com).
1128
- * Asked once per page, by GL or by a module that needs it (gl.scroll, gl.router: they stay
1129
- * native until the answer is yes). Yes on your own computer (localhost, *.test), and when
1130
- * the check can't be reached.
1324
+ * Asked once per page, by GL or by a module that needs it (umber.scroll, umber.router: they stay
1325
+ * native until the answer is yes). Yes on your own computer (localhost, *.localhost, *.test);
1326
+ * no when the check can't be reached (umber.reason "licence-unreachable"): only a clear yes counts.
1131
1327
  */
1132
1328
  licensed(): Promise<boolean>;
1133
- /** gl.licensed()'s answer once it is in; null while it is asked (or before anything asked). */
1329
+ /** umber.licensed()'s answer once it is in; null while it is asked (or before anything asked). */
1134
1330
  readonly licence: boolean | null;
1135
1331
  /**
1136
1332
  * A plane from code: writes the attributes `options` stand for and builds the plane
1137
1333
  * (now when GL is loaded). Resolves with the plane, or null when GL is off. An element
1138
- * with data-gl already resolves with its own plane.
1139
- * @example const plane = await gl.add(img, { effects: ["dissolve"], options: { dissolve: { trigger: "manual" } } })
1334
+ * with data-umber already resolves with its own plane.
1335
+ * @example const plane = await umber.add(img, { effects: ["dissolve"], options: { dissolve: { trigger: "manual" } } })
1140
1336
  */
1141
1337
  add(el: string | Element, options?: AddOptions): Promise<Plane | null>;
1142
1338
  /**
1143
- * Record every Umber object made inside fn (planes from gl.add, views, trackers,
1339
+ * Record every Umber object made inside fn (planes from umber.add, views, trackers,
1144
1340
  * progress signals, frame callbacks, events, nextFrame, definitions, nested scopes,
1145
- * targets, snapshots, sims, brushes, gl.leave, and what a module's calls make: gl.drag,
1146
- * gl.texture...); scope.revert() undoes them all. Selector strings resolve inside `container`.
1147
- * @example const scope = gl.scope(() => { gl.add(".card img", { effects: ["lens"] }); }, card); scope.revert();
1341
+ * targets, snapshots, sims, brushes, umber.leave, and what a module's calls make: umber.drag,
1342
+ * umber.texture...); scope.revert() undoes them all. Selector strings resolve inside `container`.
1343
+ * @example const scope = umber.scope(() => { umber.add(".card img", { effects: ["lens"] }); }, card); scope.revert();
1148
1344
  */
1149
1345
  scope(fn?: (scope: Scope) => unknown, container?: string | Element | null): Scope;
1150
1346
  /**
1151
1347
  * A live 0..1 as el scrolls from `start` to `end`, from the measure phase (native
1152
1348
  * scroll, a scroll container or Lenis alike; also with GL off). Usable as a uniform.
1153
1349
  * Ends when el leaves the page.
1154
- * @example gl.effect("story", { uniforms: { uStory: gl.progress(".story", { start: "top top", end: "bottom bottom" }) } })
1350
+ * @example umber.effect("story", { uniforms: { uStory: umber.progress(".story", { start: "top top", end: "bottom bottom" }) } })
1155
1351
  */
1156
1352
  progress(el: string | Element, options?: ProgressOptions): ProgressSignal;
1157
1353
  /** fn(frame) once, on the next frame (update phase unless `phase`). Returns a cancel. */
1158
1354
  nextFrame(fn: (frame: Frame) => void, opts?: { phase?: TickPhase; order?: number }): () => void;
1159
- /** Look for [data-gl] in root now (normally automatic). */
1355
+ /** Look for [data-umber] in root now (normally automatic). */
1160
1356
  scan(root?: ParentNode): void;
1161
1357
  /** Destroy planes whose element left the page (normally automatic). */
1162
1358
  prune(): void;
1163
- /** gl.destroy(): the whole engine. gl.destroy(el): that element's plane only. */
1164
- destroy(el?: Element): void;
1359
+ /** umber.destroy(): the whole engine. umber.destroy(el): that element's plane only (null, a selector that found nothing: nothing, with a warning). */
1360
+ destroy(el?: Element | null): void;
1165
1361
  /** Measure every plane (or el's) again on the next frame, and read its effect options again (a CSSOM change, an option attribute set from code). */
1166
1362
  invalidate(el?: Element): void;
1167
1363
  /** Measure every visible plane every frame: true, false, or for `seconds`. */
1168
1364
  live(on: boolean | number): void;
1169
1365
  wake(frames?: number): void;
1366
+ /** GL lets the DOM show and holds its planes until resume(). umber.loop.pause() stops the clock instead. */
1170
1367
  pause(): void;
1171
1368
  resume(): void;
1369
+ /**
1370
+ * Umber's clock: pause(), play() and restart() every frame callback at once (the page's
1371
+ * own loops too, with patch), its measured fps, and a profiler.
1372
+ * @example umber.loop.pause();
1373
+ */
1374
+ readonly loop: Loop;
1172
1375
  plane(el: Element | null | undefined): Plane | null;
1173
1376
  /**
1174
1377
  * Print one plane to the console (kind, source, tier, effects, uniforms, program) with
1175
1378
  * every reason it is not drawn, and resolve with the same report. An element inside a
1176
- * plane (the <img> in a data-gl wrapper) reports that plane. null when nothing matches.
1379
+ * plane (the <img> in a data-umber wrapper) reports that plane. null when nothing matches.
1177
1380
  * Async: what it reads comes with chunks/inspect.js, fetched on the first call.
1178
- * @example const report = await gl.inspect(".hero img")
1381
+ * @example const report = await umber.inspect(".hero img")
1179
1382
  */
1180
1383
  inspect(el: string | Element): Promise<InspectReport | null>;
1181
1384
  planes(container?: ParentNode): Plane[];
@@ -1186,7 +1389,7 @@ export interface GL {
1186
1389
  /**
1187
1390
  * A page change, for any router: call it in the hook where a change starts, and the
1188
1391
  * function it returns in the hook where it is done. Plays are held and planes measured
1189
- * every frame until then, data-gl-id images on screen are noted to fly, and an element
1392
+ * every frame until then, data-umber-id images on screen are noted to fly, and an element
1190
1393
  * with a view-transition-name shows its DOM (the browser snapshots it). Optional:
1191
1394
  * planes, swaps and flights also work without it. A second call while one runs gives it
1192
1395
  * the next page and returns the same end. Ends by itself after 8 s (with a warning).
@@ -1198,8 +1401,8 @@ export interface GL {
1198
1401
  * `finished`). Resolves once the image landed and the new page's planes on screen draw
1199
1402
  * (4 s at most), so a router hook can await it.
1200
1403
  * @example let end = () => {};
1201
- * swup.hooks.on("visit:start", () => (end = gl.transition()));
1202
- * swup.hooks.on("page:load", (visit, { page }) => gl.transition(page.html)); // Swup 4
1404
+ * swup.hooks.on("visit:start", () => (end = umber.transition()));
1405
+ * swup.hooks.on("page:load", (visit, { page }) => umber.transition(page.html)); // Swup 4
1203
1406
  * swup.hooks.on("visit:end", () => end());
1204
1407
  */
1205
1408
  transition(next?: NextPage): (after?: number | PromiseLike<unknown>) => Promise<void>;
@@ -1208,26 +1411,27 @@ export interface GL {
1208
1411
  * GL is laid over the new page and your GLSL takes it away. Define
1209
1412
  * `vec4 leave(vec2 uv)` ((0,0) = top left; premultiplied in and out); prev(uv) is the
1210
1413
  * old page, next(uv) the new one (calling it makes leave() replace the canvas instead
1211
- * of drawing over it), uProgress runs 0 -> 1 from gl.transition()'s end() (or from the
1212
- * swap, with no gl.transition()). GL content only: the DOM is the router's. Copies are
1213
- * taken only while a change may start (gl.transition(), a same-origin link pressed, a
1214
- * back / forward), from frames the page draws anyway. null turns it off.
1215
- * @example gl.leave("vec4 leave(vec2 uv) { return prev(uv) * step(uProgress, uv.y); }", { duration: 0.9 });
1414
+ * of drawing over it), uProgress runs 0 -> 1 from umber.transition()'s end() (or from the
1415
+ * swap, with no umber.transition()). GL content only: the DOM is the router's. Copies are
1416
+ * taken only while a change may start (umber.transition(), a same-origin link pressed, a
1417
+ * back / forward), from frames the page draws anyway. null turns it off. Resolves (with
1418
+ * null) once it is set, or at once when GL is off.
1419
+ * @example umber.leave("vec4 leave(vec2 uv) { return prev(uv) * step(uProgress, uv.y); }", { duration: 0.9 });
1216
1420
  */
1217
- leave(glsl: string | null, options?: LeaveOptions): Promise<void>;
1421
+ leave(glsl: string | null, options?: LeaveOptions): Promise<null>;
1218
1422
  /**
1219
1423
  * A same-page layout change, flown on the GPU (chunks/flip.js): the GL elements inside
1220
1424
  * `els` are noted where they are drawn, `change()` runs (at once, before this returns),
1221
1425
  * and each flies from its old rect and corners to its new ones. The DOM jumps; only
1222
1426
  * the GL copies move. Resolves once all landed. Without GL, change() simply runs.
1223
- * @example await gl.flip(".card", () => grid.classList.toggle("is-list"), { duration: 0.8, stagger: 0.03 });
1427
+ * @example await umber.flip(".card", () => grid.classList.toggle("is-list"), { duration: 0.8, stagger: 0.03 });
1224
1428
  */
1225
1429
  flip(els: string | Element | ArrayLike<Element>, change?: () => void, options?: FlipOptions): Promise<void>;
1226
1430
  /**
1227
- * The lower-level parts of gl.transition() for data-gl-id flights. capture(next): a
1431
+ * The lower-level parts of umber.transition() for data-umber-id flights. capture(next): a
1228
1432
  * navigation starts; when the next page is known the matching image freezes where it is
1229
1433
  * ("" or nothing = not known yet). settle(): the swap is done.
1230
- * @example barba.hooks.before((data) => gl.morph.capture(data.next.html)); barba.hooks.after(() => gl.morph.settle());
1434
+ * @example barba.hooks.before((data) => umber.morph.capture(data.next.html)); barba.hooks.after(() => umber.morph.settle());
1231
1435
  */
1232
1436
  morph: { capture(next?: NextPage): void; settle(): void };
1233
1437
  /** Where an element is, every frame, without WebGL (works with GL off). Ends when el leaves the page. */
@@ -1235,32 +1439,45 @@ export interface GL {
1235
1439
  /**
1236
1440
  * Your three.js scene in its own canvas (the drop-in mode). Umber sizes the renderer,
1237
1441
  * draws only while el is on screen and something asked, and cleans up when el leaves.
1238
- * @example gl.attach(el, { renderer, scene, camera, devices: "all", animate: (f) => { mesh.rotation.y += f.dt; return true; } })
1442
+ * @example umber.attach(el, { renderer, scene, camera, devices: "all", animate: (f) => { mesh.rotation.y += f.dt; return true; } })
1239
1443
  */
1240
- attach(el: string | Element, options: AttachOptions): View;
1444
+ attach<S, C extends ViewCameraLike | undefined, R extends ThreeRendererLike>(
1445
+ el: string | Element,
1446
+ options: AttachOptions<S, C, R>,
1447
+ ): View;
1241
1448
  /**
1242
1449
  * Advanced: a scene drawn into Umber's own canvas, next to the DOM planes, with the one
1243
- * renderer from gl.renderer(THREE). Clipped to el, fades with it, goes when el leaves.
1244
- * @example const renderer = await gl.renderer(THREE); gl.view(el, { scene, camera });
1450
+ * renderer from umber.renderer(THREE). Clipped to el, fades with it, goes when el leaves.
1451
+ * @example const renderer = await umber.renderer(THREE); umber.view(el, { scene, camera });
1452
+ */
1453
+ view<S, C extends ViewCameraLike | undefined, R extends SharedRendererLike = SharedRendererLike>(
1454
+ el: string | Element,
1455
+ options?: SharedViewOptions<S, C, R>,
1456
+ ): View;
1457
+ /**
1458
+ * Advanced: the one THREE.WebGLRenderer on Umber's canvas for the whole visit (compiled
1459
+ * programs survive page changes), made with `params` plus Umber's canvas and context.
1460
+ * Resolves with the renderer three's module makes; null when GL is off.
1245
1461
  */
1246
- view(el: string | Element, options?: SharedViewOptions): View;
1247
- /** Advanced: the one THREE.WebGLRenderer on Umber's canvas for the whole visit (compiled programs survive page changes). null when GL is off. */
1248
- renderer(three: any, params?: Record<string, unknown>): Promise<any>;
1462
+ renderer<R extends SharedRendererLike>(
1463
+ three: ThreeModuleLike<R>,
1464
+ params?: Record<string, unknown>,
1465
+ ): Promise<R | null>;
1249
1466
  /**
1250
1467
  * An offscreen render target on Umber's context (its own file, chunks/fx.js, fetched on
1251
1468
  * the first call). Draw into it with target.draw(glsl), read it in any effect as a
1252
1469
  * uniform, or hand target.texture to three.js on Umber's canvas. Holds premultiplied
1253
1470
  * alpha; "half" (RGBA16F) by default where the GPU can render to it. null when GL is off.
1254
- * @example const t = await gl.target({ width: 512, height: 512 });
1471
+ * @example const t = await umber.target({ width: 512, height: 512 });
1255
1472
  * t.draw("vec4 color(vec2 uv) { return vec4(uv, 0.5, 1.0); }");
1256
- * gl.effect("show", { uniforms: { uPattern: t }, fragment: { color: "color = texture(uPattern, uv);" } });
1473
+ * umber.effect("show", { uniforms: { uPattern: t }, fragment: { color: "color = texture(uPattern, uv);" } });
1257
1474
  */
1258
1475
  target(options?: TargetOptions): Promise<Target | null>;
1259
1476
  /**
1260
1477
  * A still copy of what one plane draws right now (its effects included, its parents'
1261
1478
  * cuts not), as a target: device px, "u8". Waits up to 5 s for the plane to be able to
1262
1479
  * draw. null when there is no plane, GL is off, or it never drew.
1263
- * @example const still = await gl.snapshot(".hero img"); gl.effect("echo", { uniforms: { uStill: still }, ... });
1480
+ * @example const still = await umber.snapshot(".hero img"); umber.effect("echo", { uniforms: { uStill: still }, ... });
1264
1481
  */
1265
1482
  snapshot(el: string | Element | Plane): Promise<Target | null>;
1266
1483
  /**
@@ -1269,9 +1486,9 @@ export interface GL {
1269
1486
  * screen. It steps after an input (a brush, the pointer, set(), wake()) and sleeps once
1270
1487
  * settled, so a still page asks for no frames. Read it in any effect as a uniform.
1271
1488
  * null when GL is off.
1272
- * @example const sim = await gl.sim({ size: 128, next: "vec4 next(vec2 uv) { return texture(state, uv) * 0.95; }" });
1273
- * gl.brush(sim, { radius: 40 }); // paints where the pointer goes
1274
- * gl.effect("ink", { uniforms: { uInk: sim }, fragment: { color: "color.rgb += texture(uInk, screenUv()).r;" } });
1489
+ * @example const sim = await umber.sim({ size: 128, next: "vec4 next(vec2 uv) { return texture(state, uv) * 0.95; }" });
1490
+ * umber.brush(sim, { radius: 40 }); // paints where the pointer goes
1491
+ * umber.effect("ink", { uniforms: { uInk: sim }, fragment: { color: "color.rgb += texture(uInk, screenUv()).r;" } });
1275
1492
  */
1276
1493
  sim(options: SimOptions): Promise<Sim | null>;
1277
1494
  /**
@@ -1279,19 +1496,19 @@ export interface GL {
1279
1496
  * (`vec4 f = texture(uFlow, screenUv()); vec2 push = (f.rg * 2.0 - 1.0) * f.a;`). Made on
1280
1497
  * the first plane that reads uFlow, or here. Called again with options, it changes them.
1281
1498
  * null when GL is off, or where half-float targets can't be rendered (uFlow then uses
1282
- * the input module's gl.touch(), when it is loaded).
1499
+ * the input module's umber.touch(), when it is loaded).
1283
1500
  */
1284
1501
  flow(options?: FlowOptions): Promise<Sim | null>;
1285
1502
  /**
1286
1503
  * Soft round stamps into one field of a sim: along the pointer's path while it moves,
1287
1504
  * and wherever brush.paint(x, y) says. null when `sim` is null.
1288
- * @example const dye = gl.brush(sim, { field: "dye", radius: 30, color: [1, 0.4, 0.2, 1] });
1505
+ * @example const dye = umber.brush(sim, { field: "dye", radius: 30, color: [1, 0.4, 0.2, 1] });
1289
1506
  */
1290
1507
  brush(sim: Sim | null, options?: BrushOptions): Brush | null;
1291
1508
  /**
1292
1509
  * Get the NEXT page ready before it is on the page (its own file, chunks/warm.js): the
1293
- * images its [data-gl] elements show fetched, decoded and on the GPU (keyed the way the
1294
- * element will ask: data-gl-src, or the srcset candidate the browser will pick), their
1510
+ * images its [data-umber] elements show fetched, decoded and on the GPU (keyed the way the
1511
+ * element will ask: data-umber-src, or the srcset candidate the browser will pick), their
1295
1512
  * programs compiled, and each drawn once offscreen. When the elements arrive they claim
1296
1513
  * all of it: the first frame does no work. Never blocks the page (uploads go in idle
1297
1514
  * moments) and never rejects. The promise is also the progress: p.value 0 -> 1, a Signal
@@ -1301,37 +1518,97 @@ export interface GL {
1301
1518
  * fine), a parsed Document, Barba's data.next ({ container } / { html } / { url }), or a
1302
1519
  * list of these. { hover: true | "selector" }: from now on, a link's page is preloaded
1303
1520
  * when the pointer slows down over it (off on Save-Data; { hover: false } stops it).
1304
- * @example barba.hooks.leave((data) => { gl.preload(data.next.url.href); }); // braces: Barba waits for a returned promise
1305
- * @example gl.preload({ hover: "a.project-link" });
1521
+ * @example barba.hooks.leave((data) => { umber.preload(data.next.url.href); }); // braces: Barba waits for a returned promise
1522
+ * @example umber.preload({ hover: "a.project-link" });
1306
1523
  */
1307
- preload(what: PreloadSource | PreloadSource[] | { hover: boolean | string }, fn?: (progress: number) => void): Loading;
1524
+ preload(
1525
+ what: PreloadSource | PreloadSource[] | { hover: boolean | string },
1526
+ fn?: (progress: number) => void,
1527
+ ): Loading;
1308
1528
  /**
1309
1529
  * Get THIS page ready (chunks/warm.js): every plane in root (default: the page) loads its
1310
1530
  * image or text even when far from the screen, compiles, and is drawn once offscreen.
1311
1531
  * Resolves when all of them can draw (each plane waits 5 s at most, once chunks/fx.js is in); p.value is a 0..1 progress for a
1312
1532
  * preloader. With GL off it resolves at once with value 1.
1313
- * @example const p = gl.warm(null, (v) => (bar.style.scale = `${v} 1`)); await p; loader.remove();
1533
+ * @example const p = umber.warm(null, (v) => (bar.style.scale = `${v} 1`)); await p; loader.remove();
1314
1534
  */
1315
1535
  warm(root?: string | ParentNode | null, fn?: (progress: number) => void): Loading;
1316
1536
  /**
1317
- * The data-gl-placeholder string for an image (about 50 characters: a preview 6 cells on
1537
+ * The data-umber-placeholder string for an image (about 50 characters: a preview 6 cells on
1318
1538
  * its long side, 4 bits per channel). Run it once (the console will do) and paste the string into the
1319
1539
  * element's attribute. null when GL is off or the file can't be read.
1320
- * @example await gl.placeholder("/img/dunes.jpg") // "UF..."
1540
+ * @example await umber.placeholder("/img/dunes.jpg") // "UF..."
1321
1541
  */
1322
1542
  placeholder(src: string | Element): Promise<string | null>;
1323
- readonly info: Record<string, unknown>;
1543
+ readonly info: UmberInfo;
1324
1544
  readonly canvas: HTMLCanvasElement | null;
1325
1545
  readonly context: WebGL2RenderingContext | null;
1326
1546
  }
1327
1547
 
1328
- /** What gl.preload() takes: an image or page URL, an element or container, a parsed Document, or a router's next page. */
1329
- export type PreloadSource = string | URL | ParentNode | { container?: ParentNode; html?: string; url?: string | { href?: string } } | null | undefined;
1548
+ /** umber.info.gpu: the device's GPU level, read once when GL starts. */
1549
+ export interface GpuInfo {
1550
+ /** 0 (software) to 5 (strong desktop GPU). */
1551
+ level: number;
1552
+ tier: "high" | "mid" | "low";
1553
+ mobile: boolean;
1554
+ renderer: string;
1555
+ /** "rule: <what matched>", "default" or "url" (?umber-gpu). */
1556
+ reason: string;
1557
+ maxTexture: number;
1558
+ /** Max bytes of image textures kept on the GPU. */
1559
+ textureBudget: number;
1560
+ /** Above this CSS width the canvas DPR is cut (createUmber dpr aside); Infinity: never. */
1561
+ wide: number;
1562
+ }
1563
+
1564
+ /** umber.info while GL runs: what the last frame did, and what the GPU holds. */
1565
+ export interface UmberStats {
1566
+ state:
1567
+ "dormant" | "asleep" | "idle" | "active" | "paused" | "off (canvas host)" | "off (context lost)" | "off (error)";
1568
+ backend: "webgl2";
1569
+ tier: "high" | "mid" | "low";
1570
+ /** null until it is read. */
1571
+ gpu: GpuInfo | null;
1572
+ fps: number;
1573
+ frameMs: number;
1574
+ renders: number;
1575
+ skipped: number;
1576
+ rendersPerSec: number;
1577
+ draws: number;
1578
+ planes: number;
1579
+ visible: number;
1580
+ textures: number;
1581
+ textureMB: number;
1582
+ gpuMB: number;
1583
+ /** What every render target holds on the GPU (absent until chunks/fx.js is here). */
1584
+ targetMB?: number;
1585
+ uploads: number;
1586
+ programs: number;
1587
+ /** Why the loop keeps drawing; [] once it sleeps. */
1588
+ busy: string[];
1589
+ dpr: number;
1590
+ scale: number;
1591
+ width: number;
1592
+ height: number;
1593
+ }
1594
+
1595
+ /** umber.info: UmberStats while GL runs; only its state before GL started; once GL went off, the last numbers it had. */
1596
+ export type UmberInfo =
1597
+ UmberStats | (Partial<Omit<UmberStats, "state">> & { state: "dormant" | `off (${UmberReason})` });
1598
+
1599
+ /** What umber.preload() takes: an image or page URL, an element or container, a parsed Document, or a router's next page. */
1600
+ export type PreloadSource =
1601
+ | string
1602
+ | URL
1603
+ | ParentNode
1604
+ | { container?: ParentNode; html?: string; url?: string | { href?: string } }
1605
+ | null
1606
+ | undefined;
1330
1607
 
1331
- /** gl.preload() / gl.warm(): resolves when ready; value is the 0..1 progress (a Signal: usable as a uniform). */
1332
- export type Loading = Promise<void> & Signal<number>;
1608
+ /** umber.preload() / umber.warm(): resolves when ready; value is the 0..1 progress (a Signal: usable as a uniform). */
1609
+ export type Loading = Promise<void> & Signal;
1333
1610
 
1334
- /** gl.leave(glsl, options). */
1611
+ /** umber.leave(glsl, options). */
1335
1612
  export interface LeaveOptions {
1336
1613
  /** Seconds uProgress takes from 0 to 1. @default 1 */
1337
1614
  duration?: number;
@@ -1339,11 +1616,11 @@ export interface LeaveOptions {
1339
1616
  ease?: Ease;
1340
1617
  /** Your own uniforms (a { value } is read every frame). uPrev, uNext and uProgress are Umber's. */
1341
1618
  uniforms?: Record<string, unknown>;
1342
- /** Arm on a pointerdown on a same-origin link and on back / forward, also with no gl.transition(). @default true */
1619
+ /** Arm on a pointerdown on a same-origin link and on back / forward, also with no umber.transition(). @default true */
1343
1620
  links?: boolean;
1344
1621
  }
1345
1622
 
1346
- /** gl.flip(els, change, options) and plane.land(options). */
1623
+ /** umber.flip(els, change, options) and plane.land(options). */
1347
1624
  export interface FlipOptions {
1348
1625
  /** Seconds. @default 0.8 */
1349
1626
  duration?: number;
@@ -1361,7 +1638,7 @@ export interface FreeRect {
1361
1638
  height: number;
1362
1639
  }
1363
1640
 
1364
- /** gl.target(options). Sizes in device px. */
1641
+ /** umber.target(options). Sizes in device px. */
1365
1642
  export interface TargetOptions {
1366
1643
  /** Default: the canvas width (device px). The target never follows the canvas: call resize(). */
1367
1644
  width?: number;
@@ -1388,7 +1665,7 @@ export interface Target {
1388
1665
  /** The first attachment's texture (null once released or while the context is lost). */
1389
1666
  readonly texture: WebGLTexture | null;
1390
1667
  /** Every attachment's texture (MRT). */
1391
- readonly textures: ReadonlyArray<WebGLTexture | null>;
1668
+ readonly textures: readonly (WebGLTexture | null)[];
1392
1669
  /** Its resolved framebuffer (for readPixels, or another library's reads). */
1393
1670
  readonly framebuffer: WebGLFramebuffer | null;
1394
1671
  readonly width: number;
@@ -1415,10 +1692,10 @@ export interface Target {
1415
1692
  release(): void;
1416
1693
  }
1417
1694
 
1418
- /** A size in texels: one number, or one per GPU level 0-5 (gl.info.gpu.level). */
1695
+ /** A size in texels: one number, or one per GPU level 0-5 (umber.info.gpu.level). */
1419
1696
  export type SimSize = number | number[];
1420
1697
 
1421
- /** gl.sim(options). Give `next` (one field, "state") or `fields` + `passes`. */
1698
+ /** umber.sim(options). Give `next` (one field, "state") or `fields` + `passes`. */
1422
1699
  export interface SimOptions {
1423
1700
  /** Texels across (or one per GPU level 0-5). @default 128 */
1424
1701
  size?: SimSize;
@@ -1439,7 +1716,7 @@ export interface SimOptions {
1439
1716
  /** Named fields: each is a sampler of its name in every pass. */
1440
1717
  fields?: Record<string, { size?: SimSize; type?: "u8" | "half" | "float"; init?: string }>;
1441
1718
  /** In order, every step: `next` writes field `into` (its old value still readable); `iterations` per step (or one per GPU level). */
1442
- passes?: Array<{ into: string; next: string; iterations?: number | number[] }>;
1719
+ passes?: { into: string; next: string; iterations?: number | number[] }[];
1443
1720
  /** The field sim.texture is. @default the first */
1444
1721
  output?: string;
1445
1722
  /** Your uniforms for every pass (numbers, arrays, targets, textures). Change them with sim.set(). */
@@ -1479,7 +1756,7 @@ export interface Sim {
1479
1756
  release(): void;
1480
1757
  }
1481
1758
 
1482
- /** gl.brush(sim, options). */
1759
+ /** umber.brush(sim, options). */
1483
1760
  export interface BrushOptions {
1484
1761
  /** The field it paints. @default the first */
1485
1762
  field?: string;
@@ -1501,7 +1778,7 @@ export interface Brush {
1501
1778
  release(): void;
1502
1779
  }
1503
1780
 
1504
- /** gl.flow(options). */
1781
+ /** umber.flow(options). */
1505
1782
  export interface FlowOptions {
1506
1783
  /** Texels across (or one per GPU level 0-5). @default [32, 48, 64, 64, 96, 128] */
1507
1784
  size?: SimSize;
@@ -1516,7 +1793,7 @@ export interface FlowOptions {
1516
1793
  /** window.Umber (the <script> build). */
1517
1794
  export interface UmberGlobal {
1518
1795
  readonly version: string;
1519
- createGL(options?: GLOptions): GL;
1796
+ createUmber(options?: UmberOptions): Umber;
1520
1797
  /** DOM <-> three.js maths and frame-rate-free smoothing. No engine needed. */
1521
1798
  readonly math: UmberMath;
1522
1799
  /** An optional module for the engine on the page and every later one (module scripts call it themselves). */
@@ -1525,8 +1802,7 @@ export interface UmberGlobal {
1525
1802
 
1526
1803
  declare global {
1527
1804
  interface Window {
1528
- Umber: UmberGlobal;
1805
+ /** The npm build's chunk folder, set before createUmber() (createUmber({ base }) wins). umber.js loads from its own folder. */
1529
1806
  UmberConfig?: { base?: string };
1530
1807
  }
1531
- const Umber: UmberGlobal;
1532
1808
  }