@occluze/umber 0.2.0 → 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 +240 -0
  63. package/docs/AI.md +3130 -0
  64. package/docs/npm.md +37 -26
  65. package/package.json +183 -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
@@ -1,28 +1,28 @@
1
- // -----------------------------------------
2
- // UMBER MODULE: HANDOFF, TYPES (@occluze/umber/handoff)
3
- // -----------------------------------------
1
+ /**
2
+ * Types for the handoff module (@occluze/umber/handoff).
3
+ *
4
+ * data-umber-id images that fly across full page loads (multi-page sites, no router), the
5
+ * canvas over cross-document View Transitions, a cover pass of your own shader, and the
6
+ * accessibility bits of a page change:
7
+ *
8
+ * import { Handoff } from "@occluze/umber/handoff";
9
+ * umber.use(Handoff, { cover: "ink" }); // or createUmber({ modules: [Handoff] })
10
+ * <script src=".../umber@x.y.z/modules/handoff.js"></script> (registers itself)
11
+ *
12
+ * umber.handoff.arrived the record this page was opened with, or null
13
+ * umber.handoff.cover("ink", { phase: "cover" }) a router's leave hook
14
+ * umber.handoff.cover("ink", { phase: "reveal" }) ... and its enter hook
15
+ * umber.handoff.announce(); umber.handoff.focus(); after a router's swap
16
+ */
4
17
 
5
- // data-gl-id images that fly across full page loads (multi-page sites, no router), the
6
- // canvas over cross-document View Transitions, a cover pass of your own shader, and the
7
- // accessibility bits of a page change:
8
- //
9
- // import { Handoff } from "@occluze/umber/handoff";
10
- // gl.use(Handoff, { cover: "ink" }); // or createGL({ modules: [Handoff] })
11
- // <script src=".../umber@x.y.z/modules/handoff.js"></script> (registers itself)
12
- //
13
- // gl.handoff.arrived the record this page was opened with, or null
14
- // gl.handoff.cover("ink", { phase: "cover" }) a router's leave hook
15
- // gl.handoff.cover("ink", { phase: "reveal" }) ... and its enter hook
16
- // gl.handoff.announce(); gl.handoff.focus(); after a router's swap
17
-
18
- import type { GL, UmberModule } from "./umber.js";
18
+ import type { Umber, UmberModule } from "./umber.js";
19
19
 
20
20
  export interface HandoffOptions {
21
21
  /** ms a leave record stays good for the next page. @default 3000 */
22
22
  maxAge?: number;
23
23
  /** Lift the canvas over a cross-document View Transition (needs layer "over"). @default true */
24
24
  vt?: boolean;
25
- /** A gl.shader() name played (revealing, from the old page's click) on a page reached through a record. @default null */
25
+ /** A umber.shader() name played (revealing, from the old page's click) on a page reached through a record. @default null */
26
26
  cover?: string | null;
27
27
  /** Seconds of that reveal. @default 0.8 */
28
28
  coverDuration?: number;
@@ -75,7 +75,7 @@ export interface CoverOptions {
75
75
  direction?: 1 | -1;
76
76
  }
77
77
 
78
- /** gl.handoff, once the module is in. */
78
+ /** umber.handoff, once the module is in. */
79
79
  export interface HandoffApi {
80
80
  /** The record this page was opened with (this URL, fresh, not a reload), or null. */
81
81
  readonly arrived: HandoffRecord | null;
@@ -85,13 +85,13 @@ export interface HandoffApi {
85
85
  readonly direction: 1 | -1;
86
86
  /** The cross-document View Transition this page was revealed with (await its finished), or null. */
87
87
  readonly viewTransition: { readonly finished: Promise<unknown> } | null;
88
- /** The module's options, live: with the script build, set them right after createGL(). */
88
+ /** The module's options, live: with the script build, set them right after createUmber(). */
89
89
  readonly options: Required<HandoffOptions>;
90
90
  /**
91
91
  * A full-screen pass of your own shader over the page. It sets uCover (0 shows the page,
92
92
  * 1 covers it), uOrigin (0..1, y down) and uDirection (1 | -1) where the shader declares
93
93
  * them. Resolves when it is done. Reduced motion: nothing plays.
94
- * @example gl.shader("ink", { uniforms: { uCover: 0, uOrigin: [0.5, 0.5], uDirection: 1 }, fragment: "..." });
94
+ * @example umber.shader("ink", { uniforms: { uCover: 0, uOrigin: [0.5, 0.5], uDirection: 1 }, fragment: "..." });
95
95
  */
96
96
  cover(shader: string, options?: CoverOptions): Promise<void>;
97
97
  /** Say text (default: document.title) in a polite live region. */
@@ -101,16 +101,17 @@ export interface HandoffApi {
101
101
  }
102
102
 
103
103
  declare module "./umber.js" {
104
- interface GL {
104
+ interface Umber {
105
105
  /** The handoff module's API (types/handoff.d.ts). */
106
106
  readonly handoff: HandoffApi;
107
107
  }
108
108
  }
109
109
 
110
- /** gl.use(Handoff), createGL({ modules: [Handoff] }). headSnippet: the <script> to paste into <head>. */
110
+ /** umber.use(Handoff), createUmber({ modules: [Handoff] }). headSnippet: the <script> to paste into <head>. */
111
111
  export declare const Handoff: UmberModule & { readonly headSnippet: string };
112
112
 
113
- /** The same without gl.use(): adds gl.handoff to `engine`. */
114
- export declare function handoff(engine: GL, options?: HandoffOptions): HandoffApi;
113
+ /** The same without umber.use(): adds umber.handoff to `engine`. */
114
+ export declare function handoff(engine: Umber, options?: HandoffOptions): HandoffApi;
115
115
 
116
+ /** @alias The same module as the named export, for `import Handoff from`. */
116
117
  export default Handoff;
package/types/input.d.ts CHANGED
@@ -1,29 +1,29 @@
1
- // -----------------------------------------
2
- // UMBER MODULE: INPUT, TYPES (@occluze/umber/input)
3
- // -----------------------------------------
4
-
5
- // Inputs as Signals: the speed of any Signal, a drag, the pointer's trail, presses and
6
- // steps; and live textures: a canvas, video or numbers, the pointer's touch trail,
7
- // element rects, an image's colour. Load the module, then use them from gl:
8
- //
9
- // import { Input } from "@occluze/umber/input";
10
- // gl.use(Input); // or createGL({ modules: [Input] })
11
- // <script src=".../umber@x.y.z/modules/input.js"></script> (registers itself)
12
- //
13
- // const d = gl.drag(".gallery", { axis: "x", bounds: { x: [-2400, 0] } });
14
- // gl.effect("bend", { uniforms: { uDrag: d, uDragSpeed: d.velocity }, ... });
15
- // const v = gl.velocityOf(gl.progress(".story")); // progress per second, 0 at rest
16
- // const t = gl.trail(16); // t.points[i].value: [x, y]
17
- // gl.effect("ripple", { uniforms: { uPress: gl.press }, ... }); // [x, y, time]
18
- // const off = gl.step(80, (at) => stamp(at)); // every 80 px the pointer travels
19
- // const mask = gl.texture(canvas); mask.update(); // uploaded only when you say it changed
20
- // gl.effect("smear", { uniforms: { uTouch: gl.touch() }, ... }); // sample with screenUv()
21
- //
22
- // Each one asks for frames only while it still moves: at rest the loop sleeps.
23
-
24
- import type { GL, Signal, UmberModule } from "./umber.js";
25
-
26
- /** What gl.velocityOf() follows: anything with a numeric value (a number or [x, y...]). */
1
+ /**
2
+ * Types for the input module (@occluze/umber/input).
3
+ *
4
+ * Inputs as Signals: the speed of any Signal, a drag, the pointer's trail, presses and
5
+ * steps; and live textures: a canvas, video or numbers, the pointer's touch trail,
6
+ * element rects, an image's colour. Load the module, then use them from gl:
7
+ *
8
+ * import { Input } from "@occluze/umber/input";
9
+ * umber.use(Input); // or createUmber({ modules: [Input] })
10
+ * <script src=".../umber@x.y.z/modules/input.js"></script> (registers itself)
11
+ *
12
+ * const d = umber.drag(".gallery", { axis: "x", bounds: { x: [-2400, 0] } });
13
+ * umber.effect("bend", { uniforms: { uDrag: d, uDragSpeed: d.velocity }, ... });
14
+ * const v = umber.velocityOf(umber.progress(".story")); // progress per second, 0 at rest
15
+ * const t = umber.trail(16); // t.points[i].value: [x, y]
16
+ * umber.effect("ripple", { uniforms: { uPress: umber.press }, ... }); // [x, y, time]
17
+ * const off = umber.step(80, (at) => stamp(at)); // every 80 px the pointer travels
18
+ * const mask = umber.texture(canvas); mask.update(); // uploaded only when you say it changed
19
+ * umber.effect("smear", { uniforms: { uTouch: umber.touch() }, ... }); // sample with screenUv()
20
+ *
21
+ * Each one asks for frames only while it still moves: at rest the loop sleeps.
22
+ */
23
+
24
+ import type { Umber, Signal, UmberModule } from "./umber.js";
25
+
26
+ /** What umber.velocityOf() follows: anything with a numeric value (a number or [x, y...]). */
27
27
  export interface Readable {
28
28
  readonly value: number | ArrayLike<number>;
29
29
  }
@@ -35,7 +35,7 @@ export interface VelocityOptions {
35
35
  rest?: number;
36
36
  }
37
37
 
38
- /** gl.velocityOf(signal): units per second, smoothed; exactly 0 once the signal rests. */
38
+ /** umber.velocityOf(signal): units per second, smoothed; exactly 0 once the signal rests. */
39
39
  export interface VelocitySignal<T = number | number[]> {
40
40
  readonly value: T;
41
41
  readonly destroyed: boolean;
@@ -62,7 +62,7 @@ export interface DragOptions {
62
62
  }
63
63
 
64
64
  /**
65
- * gl.drag(el): a drag as a Signal. Writes nothing to the DOM. Give the element
65
+ * umber.drag(el): a drag as a Signal. Writes nothing to the DOM. Give the element
66
66
  * touch-action: pan-y (axis "x"), pan-x (axis "y") or none in its CSS.
67
67
  */
68
68
  export interface DragSignal {
@@ -85,8 +85,8 @@ export interface DragSignal {
85
85
  on(event: DragEvent, fn: (d: DragSignal) => void): () => void;
86
86
  off(event: DragEvent, fn: (d: DragSignal) => void): void;
87
87
  /**
88
- * Automatic when its gl.scope() reverts or the engine goes; for gl.drag(element), also when
89
- * el leaves the page. A selector's waits for its next match instead, and a newer gl.drag()
88
+ * Automatic when its umber.scope() reverts or the engine goes; for umber.drag(element), also when
89
+ * el leaves the page. A selector's waits for its next match instead, and a newer umber.drag()
90
90
  * of the same selector replaces it.
91
91
  */
92
92
  destroy(): void;
@@ -98,20 +98,20 @@ export interface TrailOptions {
98
98
  follow?: number;
99
99
  }
100
100
 
101
- /** gl.trail(count): points[0] is the pointer, each next one follows the one before. */
101
+ /** umber.trail(count): points[0] is the pointer, each next one follows the one before. */
102
102
  export interface Trail {
103
103
  /** Each a vec2 Signal: uniforms: { uTail: trail.points[15] }. */
104
- readonly points: ReadonlyArray<Readonly<Signal<[number, number]>>>;
104
+ readonly points: readonly Readonly<Signal<[number, number]>>[];
105
105
  readonly destroyed: boolean;
106
106
  destroy(): void;
107
107
  }
108
108
 
109
- /** gl.press: the last press anywhere on the page. A vec3 uniform as it is. */
109
+ /** umber.press: the last press anywhere on the page. A vec3 uniform as it is. */
110
110
  export interface PressSignal {
111
111
  /** [x, y, time]: viewport px, and seconds in uTime's clock (-10000 before the first press). */
112
112
  readonly value: [number, number, number];
113
113
  /** The last 4 presses, newest first, each [x, y, time] (vec3 Signals). */
114
- readonly recent: ReadonlyArray<Readonly<Signal<[number, number, number]>>>;
114
+ readonly recent: readonly Readonly<Signal<[number, number, number]>>[];
115
115
  /** Presses so far. */
116
116
  readonly count: number;
117
117
  on(event: "press", fn: (p: PressSignal) => void): () => void;
@@ -157,19 +157,19 @@ export interface TouchOptions {
157
157
  fade?: number;
158
158
  }
159
159
 
160
- /** gl.touch(): a = ink (0..1), rg = the way the pointer moved (rg * 2.0 - 1.0). Sample it with screenUv(). */
160
+ /** umber.touch(): a = ink (0..1), rg = the way the pointer moved (rg * 2.0 - 1.0). Sample it with screenUv(). */
161
161
  export interface TouchTexture extends LiveTexture {
162
162
  readonly canvas: HTMLCanvasElement | OffscreenCanvas;
163
163
  }
164
164
 
165
- /** gl.rects(): N x 1 RGBA32F texels, each x, y, width, height in viewport px (like uRect). */
165
+ /** umber.rects(): N x 1 RGBA32F texels, each x, y, width, height in viewport px (like uRect). */
166
166
  export interface RectsTexture extends LiveTexture {
167
167
  readonly count: number;
168
168
  /** The same numbers, 4 per element. */
169
169
  readonly rects: Float32Array;
170
170
  }
171
171
 
172
- /** gl.imageColor(el): a vec4 Signal of the image's average colour, sRGB 0..1 ([0, 0, 0, 0] until known). */
172
+ /** umber.imageColor(el): a vec4 Signal of the image's average colour, sRGB 0..1 ([0, 0, 0, 0] until known). */
173
173
  export interface ImageColor {
174
174
  readonly value: [number, number, number, number];
175
175
  /** The most common colour (its pixels' average). */
@@ -178,58 +178,66 @@ export interface ImageColor {
178
178
  readonly ready: Promise<boolean>;
179
179
  }
180
180
 
181
- /** What gl.use(Input) adds to gl. */
181
+ /** What umber.use(Input) adds to gl. */
182
182
  export interface InputMethods {
183
183
  /**
184
184
  * A <canvas>, ImageBitmap, <video>, <img>, ImageData or { data, width, height } as a
185
185
  * sampler2D uniform, uploaded only after update() (a <video>: each new frame it shows).
186
- * @example const mask = gl.texture(canvas); gl.effect("reveal", { uniforms: { uMask: mask }, ... }); mask.update();
186
+ * @example const mask = umber.texture(canvas); umber.effect("reveal", { uniforms: { uMask: mask }, ... }); mask.update();
187
187
  */
188
188
  texture(source: TextureInput, options?: TextureOptions): LiveTexture;
189
189
  /**
190
190
  * The pointer's fading trail, screen-sized: sample it with screenUv(). Sleeps when faded.
191
- * @example gl.effect("smear", { uniforms: { uTouch: gl.touch() }, ... })
191
+ * @example umber.effect("smear", { uniforms: { uTouch: umber.touch() }, ... })
192
192
  */
193
193
  touch(options?: TouchOptions): TouchTexture;
194
194
  /**
195
195
  * The rects of these elements as an N x 1 texture (texelFetch(uCards, ivec2(i, 0), 0)).
196
- * @example const cards = gl.rects(".card");
196
+ * @example const cards = umber.rects(".card");
197
197
  */
198
198
  rects(target: string | ArrayLike<Element>): RectsTexture;
199
199
  /**
200
- * The average and dominant colour of el's image (data-gl-src or its <img>), once.
201
- * @example plane.set("uBg", gl.imageColor(el))
200
+ * The average and dominant colour of el's image (data-umber-src or its <img>), once.
201
+ * @example plane.set("uBg", umber.imageColor(el))
202
202
  */
203
203
  imageColor(el: string | Element): ImageColor;
204
204
  /**
205
- * The speed of any Signal (gl.progress, gl.drag, a { get value() } over a slider's
205
+ * The speed of any Signal (umber.progress, umber.drag, a { get value() } over a slider's
206
206
  * progress), sampled on every frame Umber runs. A value your code moves between frames
207
- * wakes the loop with gl.wake().
208
- * @example const v = gl.velocityOf(gl.progress(".story"), { smooth: 0.2 });
207
+ * wakes the loop with umber.wake().
208
+ * @example const v = umber.velocityOf(umber.progress(".story"), { smooth: 0.2 });
209
209
  */
210
- velocityOf<T extends number | ArrayLike<number>>(signal: { readonly value: T }, options?: VelocityOptions): VelocitySignal<T extends number ? number : number[]>;
211
- /** @example const d = gl.drag(".slider", { axis: "x", bounds: { x: [-1200, 0] } }); */
210
+ velocityOf<T extends number | ArrayLike<number>>(
211
+ signal: { readonly value: T },
212
+ options?: VelocityOptions,
213
+ ): VelocitySignal<T extends number ? number : number[]>;
214
+ /** @example const d = umber.drag(".slider", { axis: "x", bounds: { x: [-1200, 0] } }); */
212
215
  drag(el: string | Element, options?: DragOptions): DragSignal;
213
- /** @example const t = gl.trail(8, { follow: 0.35 }); */
216
+ /** @example const t = umber.trail(8, { follow: 0.35 }); */
214
217
  trail(count?: number, options?: TrailOptions): Trail;
215
218
  /** Made (one passive pointerdown listener) the first time it is read. */
216
219
  readonly press: PressSignal;
217
220
  /**
218
221
  * fn(at, n) each time the pointer travelled another `every` px. Returns off().
219
- * @example const off = gl.step(80, ([x, y]) => stamp(x, y));
222
+ * @example const off = umber.step(80, ([x, y]) => stamp(x, y));
220
223
  */
221
224
  step(every: number, fn: (at: [number, number], n: number) => void): () => void;
222
225
  }
223
226
 
224
- // gl.velocityOf, gl.drag, gl.trail, gl.press, gl.step, gl.texture, gl.touch, gl.rects and gl.imageColor, once the module is in.
227
+ // umber.velocityOf, umber.drag, umber.trail, umber.press, umber.step, umber.texture, umber.touch, umber.rects and umber.imageColor, once the module is in;
228
+ // a umber.scope() carries the methods (s.drag...), and what they make is the scope's.
225
229
  declare module "./umber.js" {
226
- interface GL extends InputMethods {}
230
+ // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- module augmentation: merges InputMethods into GL
231
+ interface Umber extends InputMethods {}
232
+ // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- module augmentation: merges the methods into Scope
233
+ interface Scope extends Omit<InputMethods, "press"> {}
227
234
  }
228
235
 
229
- /** gl.use(Input), createGL({ modules: [Input] }). */
236
+ /** umber.use(Input), createUmber({ modules: [Input] }). */
230
237
  export declare const Input: UmberModule;
231
238
 
232
- /** The same without gl.use(): adds the methods to `engine`. */
233
- export declare function input(engine: GL): void;
239
+ /** The same without umber.use(): adds the methods to `engine`. */
240
+ export declare function input(engine: Umber): void;
234
241
 
242
+ /** @alias The same module as the named export, for `import Input from`. */
235
243
  export default Input;
@@ -0,0 +1,75 @@
1
+ /**
2
+ * Umber's clock as a site sees it (re-exported by umber.d.ts): umber.on("frame") options,
3
+ * umber.loop (pause, play, restart, fps, the profiler), and what createUmber({ patch }) takes.
4
+ */
5
+
6
+ import type { TickPhase } from "./umber.js";
7
+
8
+ /** GSAP as createUmber({ patch: { gsap } }) needs it: its ticker, woken again to ask for its frames through the patch. */
9
+ export interface GsapLike {
10
+ ticker: { wake(): void };
11
+ }
12
+
13
+ /** How a umber.on("frame") callback runs. */
14
+ export interface FrameOptions {
15
+ /** @default "update" */
16
+ phase?: TickPhase;
17
+ /** Lower runs first inside its phase. @default 0 */
18
+ order?: number;
19
+ /** false: only ride along on frames Umber runs anyway. @default true */
20
+ always?: boolean;
21
+ /**
22
+ * Its own rate: at most this many runs a second (30), or a share of the frames the loop
23
+ * runs ("50%": every other one). dt is then the time since it last ran.
24
+ * @example umber.on("frame", collide, { fps: 30 })
25
+ */
26
+ fps?: number | `${number}%`;
27
+ /** Its name in the profiler (umber.loop.profile()). */
28
+ label?: string;
29
+ }
30
+
31
+ /** umber.loop: Umber's clock as a whole (with createUmber({ patch: true }), the page's loops too). */
32
+ export interface Loop {
33
+ /** Stop every frame callback (and the patched loops) until play(). Unlike umber.pause(), GL keeps its planes on screen as they are. */
34
+ pause(): void;
35
+ /** Go on where it stopped: frame.time does not jump. */
36
+ play(): void;
37
+ /** frame.time and frame.frame from 0 again, and play. */
38
+ restart(): void;
39
+ readonly playing: boolean;
40
+ /** The screen's frame rate, as last measured. */
41
+ readonly fps: number;
42
+ /**
43
+ * A panel showing what each frame callback (and patched loop) costs, against the frame's
44
+ * budget, with a play / pause button (chunks/profiler.js, fetched on the first call). Also
45
+ * ?umber-debug=profiler with the debug module.
46
+ * @example const profiler = await umber.loop.profile(); profiler.destroy();
47
+ * @example const p = await umber.loop.profile({ panel: false }); setTimeout(() => console.table(p.read()), 2000);
48
+ */
49
+ profile(options?: ProfilerOptions): Promise<Profiler>;
50
+ }
51
+
52
+ export interface ProfilerOptions {
53
+ /** @default "top-right" */
54
+ corner?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
55
+ /** false: time the callbacks without showing a panel (read them with profiler.read()). @default true */
56
+ panel?: boolean;
57
+ }
58
+
59
+ /** One frame callback (or patched page loop) as the profiler measured it. */
60
+ export interface ProfileLine {
61
+ label: string;
62
+ phase: TickPhase;
63
+ order: number;
64
+ /** "30 fps", "50%", "page" (one of the page's own loops, patched in), or "". */
65
+ rate: string;
66
+ /** ms per frame, averaged over about a second. */
67
+ ms: number;
68
+ }
69
+
70
+ /** What umber.loop.profile() resolves with. */
71
+ export interface Profiler {
72
+ /** Every callback timed so far, in the order they run. */
73
+ read(): ProfileLine[];
74
+ destroy(): void;
75
+ }
@@ -0,0 +1,108 @@
1
+ /**
2
+ * Types for an add-on's plane hooks (@occluze/umber/module).
3
+ *
4
+ * For writing your own add-on: what UmberModule.plane() gets for each plane whose element
5
+ * carries one of its attributes, and what it hands back (a frame source, GLSL, a handle at
6
+ * plane[name]). Types only: import them where the add-on is written.
7
+ *
8
+ * import type { PlaneModuleContext, PlaneModuleBinding } from "@occluze/umber/module";
9
+ *
10
+ * With script tags and TypeScript, copy it next to types/umber.d.ts.
11
+ */
12
+
13
+ import type { EffectDef, Float32s, Frame, Umber, ModuleLog, Plane } from "./umber.js";
14
+
15
+ declare module "./umber.js" {
16
+ interface UmberModule {
17
+ /** For every plane whose element has one of its attributes, before the plane's program is built. */
18
+ plane?(ctx: PlaneModuleContext): PlaneModuleBinding | null | undefined;
19
+ }
20
+ }
21
+
22
+ /** What module.plane() gets. */
23
+ export interface PlaneModuleContext {
24
+ el: HTMLElement;
25
+ /** The plane (what umber.plane(el) returns). */
26
+ plane: Plane;
27
+ engine: Umber;
28
+ /** The element's <video> or <img>, if it has one. */
29
+ media: HTMLVideoElement | HTMLImageElement | null;
30
+ /** umber.use(module, options). */
31
+ options: Record<string, unknown>;
32
+ /** This plane's GPU frames (made on first read): a source uploads into it and picks what is drawn. */
33
+ readonly frames: FrameCache;
34
+ /** Device tier ("high" desktop, "mid" phones, "low" weak GPUs): for memory budgets. */
35
+ tier: "high" | "mid" | "low";
36
+ /** Largest texture side this device gets. */
37
+ maxTexture: number;
38
+ isTouch: boolean;
39
+ readonly reducedMotion: boolean;
40
+ /** What the engine reads scroll from. */
41
+ scrollKind: "window" | "element" | "lenis" | "object";
42
+ /** The engine's console: warnings and errors as the engine's own (shown once each), info with debug on. */
43
+ log: ModuleLog & { info(...args: unknown[]): void };
44
+ /** Draw every frame while on (smoothing towards a target). */
45
+ busy(on: boolean): void;
46
+ /** Draw at least one more frame. */
47
+ wake(): void;
48
+ /** Give this element back to the DOM for the visit (its <video> / poster shows). */
49
+ fail(message?: string): void;
50
+ }
51
+
52
+ /** What module.plane() returns. Every member is optional. */
53
+ export interface PlaneModuleBinding {
54
+ /** The public handle, at plane[module.name] (umber.plane(el).scrub). */
55
+ api?: unknown;
56
+ /** GLSL drawn first on this plane, before its own effects (its uniforms are added to the plane). */
57
+ effect?: EffectDef;
58
+ /** true: the plane's pixels come from its FrameCache, never from its <img> / <video>. */
59
+ source?: boolean;
60
+ /** Came near the screen (true, also the first time: start loading) or went far (false: free memory). */
61
+ near?(on: boolean): void;
62
+ /** On screen or not. */
63
+ visible?(on: boolean): void;
64
+ /**
65
+ * Update phase, every frame while near or on screen. `rect`: the plane's viewport rect
66
+ * (x, y, w, h); `viewport`: the visible screen. Return true when the picture changed.
67
+ */
68
+ update?(frame: Frame, rect: Float32s<4>, viewport: { width: number; height: number }): boolean | undefined;
69
+ /** The WebGL context was lost: every GPU frame is gone. */
70
+ lost?(): void;
71
+ /** The context is back (frames are empty: upload again). */
72
+ restored?(): void;
73
+ /** The plane is going (element left, umber.destroy). */
74
+ destroy?(): void;
75
+ /** Its <video> got a new src: false keeps the plane (the module wrote it), else it is built again. */
76
+ src?(): boolean;
77
+ }
78
+
79
+ /** Pixels a FrameCache accepts: a decoded VideoFrame, an ImageBitmap, a <video> or <img>, a canvas. */
80
+ export type FrameImage = TexImageSource | { displayWidth: number; displayHeight: number; close(): void };
81
+
82
+ /**
83
+ * A plane's GPU frame cache: numbered frames as textures, kept up to a memory budget around
84
+ * a playhead, two of them drawn mixed. Uploads happen in the render phase, a few per frame.
85
+ */
86
+ export interface FrameCache {
87
+ /** Upload frame `index` in the next render. close: free `image` after that (VideoFrame, ImageBitmap). */
88
+ put(index: number, image: FrameImage, close?: boolean): void;
89
+ /** Uploaded or waiting to be. */
90
+ has(index: number): boolean;
91
+ /** Uploaded: drawable now. */
92
+ ready(index: number): boolean;
93
+ /** Draw frame a, mixed towards frame b by `mix` (0..1). */
94
+ show(a: number, b?: number, mix?: number): void;
95
+ /** The playhead: frames far from it are dropped first when the budget is full. */
96
+ focus(index: number): void;
97
+ /** Max bytes of frames kept on the GPU. */
98
+ budget: number;
99
+ readonly bytes: number;
100
+ /** Frames on the GPU. */
101
+ readonly size: number;
102
+ /** Uploaded frame numbers. */
103
+ keys(): number[];
104
+ /** How many frames of width x height fit in the budget. */
105
+ capacity(width: number, height: number): number;
106
+ /** Free every frame (keepShown: but the one on screen, for a plane that went far). */
107
+ clear(keepShown?: boolean): void;
108
+ }
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Types for @occluze/umber/react: useScroll(), Lenis's useLenis() for Umber's umber.scroll.
3
+ *
4
+ * import { useScroll } from "@occluze/umber/react";
5
+ * const scroll = useScroll((s) => setProgress(s.progress), []);
6
+ */
7
+
8
+ import type { ScrollApi } from "./scroll.js";
9
+
10
+ /** umber.scroll (null until mounted, or without the scroll module); `callback` hears its "scroll" while mounted. The engine: the one on the page, or `gl`. */
11
+ export declare function useScroll(
12
+ callback?: (scroll: ScrollApi) => void,
13
+ deps?: readonly unknown[],
14
+ gl?: { readonly scroll?: ScrollApi } | null,
15
+ ): ScrollApi | null;