@occluze/umber 0.3.0 → 0.4.1

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 (87) hide show
  1. package/README.md +93 -47
  2. package/THIRD-PARTY-NOTICES.md +33 -0
  3. package/dist/chunks/badge.js +2 -2
  4. package/dist/chunks/basis.js +2 -2
  5. package/dist/chunks/batches.js +2 -0
  6. package/dist/chunks/capture.js +2 -2
  7. package/dist/chunks/covers.js +2 -2
  8. package/dist/chunks/curves.js +2 -2
  9. package/dist/chunks/flip.js +2 -2
  10. package/dist/chunks/fx.js +2 -2
  11. package/dist/chunks/gl.js +2 -2
  12. package/dist/chunks/glsl.js +2 -2
  13. package/dist/chunks/glyphs.js +2 -0
  14. package/dist/chunks/inspect.js +2 -2
  15. package/dist/chunks/instances.js +2 -2
  16. package/dist/chunks/layers.js +2 -2
  17. package/dist/chunks/licence.js +2 -2
  18. package/dist/chunks/morph.js +2 -2
  19. package/dist/chunks/pace.js +2 -0
  20. package/dist/chunks/patch.js +2 -2
  21. package/dist/chunks/prepared.js +2 -2
  22. package/dist/chunks/profiler.js +2 -2
  23. package/dist/chunks/recheck.js +2 -0
  24. package/dist/chunks/resize.js +2 -0
  25. package/dist/chunks/restore.js +2 -2
  26. package/dist/chunks/shapes.js +2 -2
  27. package/dist/chunks/sim.js +2 -2
  28. package/dist/chunks/text.js +2 -2
  29. package/dist/chunks/video.js +2 -2
  30. package/dist/chunks/vocabulary.js +2 -2
  31. package/dist/chunks/warm.js +2 -2
  32. package/dist/modules/debug.js +2 -2
  33. package/dist/modules/debug.mjs +2 -2
  34. package/dist/modules/handoff.js +2 -2
  35. package/dist/modules/handoff.mjs +2 -2
  36. package/dist/modules/input.js +2 -2
  37. package/dist/modules/input.mjs +2 -2
  38. package/dist/modules/scrollfx.js +2 -2
  39. package/dist/modules/scrollfx.mjs +2 -2
  40. package/dist/modules/scrub.js +2 -2
  41. package/dist/modules/scrub.mjs +2 -2
  42. package/dist/modules/three.js +2 -2
  43. package/dist/modules/three.mjs +2 -2
  44. package/dist/node/assets.mjs +4 -2
  45. package/dist/node/astro.mjs +26 -18
  46. package/dist/node/cli.mjs +63 -10
  47. package/dist/node/shared-NFSQ5J4B.mjs +2116 -0
  48. package/dist/node/{shared-4FIU6DYP.mjs → shared-OUFNIXQ7.mjs} +106 -17
  49. package/dist/node/vite.mjs +7 -3
  50. package/dist/prepared.mjs +2 -0
  51. package/dist/umber.css +1 -1
  52. package/dist/umber.js +2 -2
  53. package/dist/umber.mjs +2 -2
  54. package/docs/AI-quick.md +43 -87
  55. package/docs/AI.md +1977 -1829
  56. package/docs/npm.md +13 -16
  57. package/package.json +32 -48
  58. package/types/assets.d.ts +109 -4
  59. package/types/astro.d.ts +20 -23
  60. package/types/debug.d.ts +1 -1
  61. package/types/esm.d.ts +2 -6
  62. package/types/input.d.ts +3 -3
  63. package/types/loop.d.ts +21 -9
  64. package/types/module.d.ts +0 -2
  65. package/types/scrollfx.d.ts +5 -41
  66. package/types/scrub.d.ts +2 -2
  67. package/types/three.d.ts +26 -1
  68. package/types/umber.d.ts +152 -155
  69. package/types/vite.d.ts +3 -3
  70. package/dist/chunks/views.js +0 -2
  71. package/dist/frameworks/astro.mjs +0 -2
  72. package/dist/frameworks/react.mjs +0 -2
  73. package/dist/frameworks/svelte.mjs +0 -2
  74. package/dist/frameworks/vue.mjs +0 -2
  75. package/dist/modules/router-swap.js +0 -2
  76. package/dist/modules/router.js +0 -2
  77. package/dist/modules/router.mjs +0 -2
  78. package/dist/modules/scroll-more.js +0 -2
  79. package/dist/modules/scroll-touch.js +0 -2
  80. package/dist/modules/scroll.js +0 -2
  81. package/dist/modules/scroll.mjs +0 -2
  82. package/dist/node/shared-3Q24RNIF.mjs +0 -602
  83. package/types/react.d.ts +0 -15
  84. package/types/router.d.ts +0 -223
  85. package/types/scroll.d.ts +0 -190
  86. package/types/svelte.d.ts +0 -16
  87. package/types/vue.d.ts +0 -14
package/types/umber.d.ts CHANGED
@@ -21,8 +21,8 @@
21
21
  * and what it's set to: data-umber="<kind> <behaviours>", then one attribute per setting.
22
22
  *
23
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)
24
+ * scroller (the element that scrolls)
25
+ * behaviours: above, pin, horizontal, inview (scrollfx)
26
26
  * with a value, the long form only: data-umber-pin="80px", data-umber-inview="shown"
27
27
  *
28
28
  * data-umber="group" draws the GL planes inside it as one, through its
@@ -34,6 +34,7 @@
34
34
  * data-umber-<effect>-trigger auto (default) | scroll | load | manual | hover, for effects with `play`
35
35
  * data-umber-<effect>-delay / -duration / -ease / -start the play's timing ("top 90%")
36
36
  * data-umber-<effect>-repeat "reverse" | "true": plays again
37
+ * data-umber-<effect>-hide="false" a play that does not hide its element while GL loads
37
38
  * data-umber-shader="name" with data-umber="shader": the umber.shader() it draws
38
39
  * data-umber-layer="name" with data-umber="layer": the umber.layer() it runs
39
40
  * data-umber-src="url" another image than the <img> inside
@@ -67,12 +68,12 @@
67
68
  * From JS: umber.add(el, { type, effects, options }) writes these attributes for you.
68
69
  * Written by Umber: html.has-umber, data-umber-status="loading|ready|error", data-umber-media,
69
70
  * 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
+ * data-umber-view="loading|ready|off|error|lost" on umber.view() elements.
71
72
  */
72
73
 
73
74
  /**
74
75
  * The next page, as a router hands it over: its HTML, a parsed Document, its container
75
- * (or a fragment), Barba's cached { html }, or a promise of any of them. "" or null: not
76
+ * (or a fragment), a router's cached { html }, or a promise of any of them. "" or null: not
76
77
  * known yet.
77
78
  */
78
79
  export type NextPage =
@@ -83,27 +84,28 @@ export type NextPage =
83
84
  | undefined
84
85
  | PromiseLike<string | ParentNode | { html?: string } | null | undefined>;
85
86
 
86
- /** A plain { value } anyone can animate (GSAP, Motion, your own code) or read. */
87
- export interface Signal<T = number> {
88
- value: T;
89
- }
90
-
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 {
93
- animatedScroll?: number;
94
- scroll?: number;
95
- velocity?: number;
96
- isHorizontal?: boolean;
97
- options?: { wrapper?: Window | Element; orientation?: string };
98
- on(event: "scroll", fn: () => void): unknown;
99
- off?(event: "scroll", fn: () => void): unknown;
87
+ /** umber.transition()'s second argument: what the site knows about the page change. */
88
+ export interface TransitionOptions {
89
+ /**
90
+ * The container that is leaving, while the next page is in the document with it. From
91
+ * the call that names it until end(), GL draws nothing of it and its elements show their
92
+ * DOM: when the new page's DOM lies over the old page's, the old page's GL is no longer
93
+ * drawn over the new page. Give it in the first call, or in a later one at the moment
94
+ * the old page should hand over (a second call adds to the change that runs).
95
+ */
96
+ leaving?: Element | null;
97
+ /**
98
+ * How long the change may run with no end(), in seconds, before Umber ends it with a
99
+ * warning. For a site whose page changes take longer than the default. Read in the call
100
+ * that starts the change.
101
+ * @default 8
102
+ */
103
+ timeout?: number;
100
104
  }
101
105
 
102
- export interface ScrollObject {
103
- x?: number | (() => number);
104
- y?: number | (() => number);
105
- /** px per frame. Omit it to let Umber work it out from the position. */
106
- velocity?: number | (() => number);
106
+ /** A plain { value } anyone can animate (an animation library, your own code) or read. */
107
+ export interface Signal<T = number> {
108
+ value: T;
107
109
  }
108
110
 
109
111
  export interface Env {
@@ -120,33 +122,29 @@ export interface UmberOptions {
120
122
  /** Your account's public key, from your occluze dashboard. Also data-umber-key on the umber.js tag. */
121
123
  key?: string;
122
124
  /**
123
- * Where Umber reads scroll from, read-only: it never creates, drives or configures it.
124
- * The default also follows <body> when it is the page's scroller (html { overflow: hidden }).
125
+ * What scrolls, when it is not the window: the element whose own scroll position moves
126
+ * (also data-umber="scroller" on that element). Read-only: Umber never creates, drives or
127
+ * configures a scroller, and a smooth scroller needs no option, since Umber reads where it
128
+ * puts the page. The default also follows <body> when it is the page's scroller
129
+ * (html { overflow: hidden }).
125
130
  * @default window
126
- * @example createUmber({ scroll: lenis }) // your Lenis instance
127
131
  * @example createUmber({ scroll: document.querySelector(".scroller") })
128
- * @example createUmber({ scroll: { y: () => myScroll.y } }) // anything else
129
- */
130
- scroll?: Window | Element | SmoothScrollLike | ScrollObject | null;
131
- /**
132
- * "auto": Umber runs its own requestAnimationFrame loop, which sleeps when nothing moves.
133
- * false: nothing runs until you call umber.render(time) from your own loop.
134
- * @default "auto"
135
- * @example createUmber({ loop: false }); gsap.ticker.add((t) => umber.render(t * 1000));
136
132
  */
137
- loop?: "auto" | false;
133
+ scroll?: Window | Element | null;
138
134
  /**
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).
135
+ * One clock for the whole page: the page's own requestAnimationFrame loops (a smooth
136
+ * scroller, an animation library's ticker, a 3D renderer, minified code) run inside Umber's
137
+ * frame, one requestAnimationFrame per frame: the page's loops first, then Umber reads the
138
+ * page and draws. Any library fits that asks the page's requestAnimationFrame for its
139
+ * frames after the patch: none is known by name. The loop still sleeps when nothing asks
140
+ * for frames, and while only the page's loops ask, Umber's own part of the frame rests.
141
+ * Best without code: data-umber-patch on umber.js's script tag, placed before the other
142
+ * libraries' tags (patched as the script runs, so every loop started after it is caught).
145
143
  * @default false
146
- * @example createUmber({ scroll: lenis, patch: true })
147
- * @example createUmber({ patch: { gsap } }) // a bundled GSAP, not on window
144
+ * @example <script src="umber.js" data-umber-patch></script>
145
+ * @example createUmber({ patch: true })
148
146
  */
149
- patch?: boolean | { gsap?: GsapLike };
147
+ patch?: boolean;
150
148
  /**
151
149
  * Which devices draw DOM planes in GL (the rest keep the plain DOM, and nothing downloads).
152
150
  * "desktop" = hover + fine pointer + at least 768 px wide. Anything else is "desktop", with a warning.
@@ -223,13 +221,12 @@ export interface UmberOptions {
223
221
  * noted), with no hook to write. Off by default (a flag a site forgets to clear would
224
222
  * keep Umber measuring); it ends by itself after 8 s and starts again only once <html>
225
223
  * stopped matching in between.
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
224
+ * @example createUmber({ busy: "html.is-changing" }) // a class the router sets
225
+ * @example createUmber({ busy: 'html[aria-busy="true"]' }) // an attribute it sets
229
226
  */
230
227
  busy?: string;
231
228
  /**
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.
229
+ * The folder the engine's chunks (chunks/gl.js and the rest) load from.
233
230
  * @default the folder umber.js came from (npm: this version's CDN folder, or window.UmberConfig.base)
234
231
  * @example createUmber({ base: "/vendor/umber/" })
235
232
  */
@@ -380,17 +377,21 @@ export type UmberReason =
380
377
  | "context"
381
378
  | "load-failed"
382
379
  | "load-timeout"
383
- | "unlicensed"
384
- | "licence-unreachable"
380
+ | "blocked"
385
381
  | "context-lost"
386
382
  | "error"
387
383
  | "server"
388
384
  | "destroyed";
389
385
 
386
+ /**
387
+ * Where in Umber's part of the frame a umber.on("frame") callback runs: "measure" (layout
388
+ * reads), "update" (math and writes), "render" (drawing). What moves the page runs before
389
+ * all three, in umber.on("step").
390
+ */
390
391
  export type TickPhase = "measure" | "update" | "render";
391
392
 
392
- export type { FrameOptions, GsapLike, Loop, ProfileLine, Profiler, ProfilerOptions } from "./loop.js";
393
- import type { FrameOptions, GsapLike, Loop } from "./loop.js";
393
+ export type { FrameOptions, Loop, ProfileLine, Profiler, ProfilerOptions, StepOptions } from "./loop.js";
394
+ import type { FrameOptions, Loop, StepOptions } from "./loop.js";
394
395
 
395
396
  export interface Frame {
396
397
  /** Seconds since the engine started, lag-smoothed. */
@@ -448,7 +449,7 @@ export type PlaneEvent = "ready" | "enter" | "leave" | "resize" | "error" | "des
448
449
  * One line, word or character of a GL text (plane.text). `t`, `x`, `y`, `z` are four
449
450
  * plain numbers per unit (0 at first) that any library can tween; their meaning is the
450
451
  * effect's. They are kept by index when the text rewraps.
451
- * @example gsap.to(umber.plane(h1).text.lines, { t: 1, stagger: 0.08 })
452
+ * @example umber.plane(h1).text.lines.forEach((line, i) => line.tween("t", { value: 1, delay: i * 0.08 }))
452
453
  */
453
454
  export interface TextUnit {
454
455
  /** 0-based, in reading order: the same numbers as glyph() in GLSL. */
@@ -552,9 +553,9 @@ export interface Plane {
552
553
  play(vars?: Partial<TweenVars> & { uniform?: string }): Tween | null;
553
554
  /**
554
555
  * Let go of its element (chunks/flip.js): resolves with its rect, viewport CSS px, to
555
- * move with anything (GSAP...). It stays put on screen while the page scrolls, and its
556
+ * move with anything (your own tween, an animation library). It stays put on screen while the page scrolls, and its
556
557
  * element's own DOM stays hidden. land() flies it home.
557
- * @example const r = await plane.lift(); gsap.to(r, { x: 0, y: 0, width: innerWidth, height: innerHeight });
558
+ * @example const r = await plane.lift(); Object.assign(r, { x: 0, y: 0, width: innerWidth, height: innerHeight });
558
559
  */
559
560
  lift(): Promise<FreeRect | null>;
560
561
  /** Fly home to its element from wherever it is drawn (after lift()). */
@@ -656,14 +657,19 @@ export interface EffectContext<O extends OptionDefaults = OptionDefaults> {
656
657
  /**
657
658
  * An effect: GLSL snippets for named slots plus uniforms. The slots, inputs and helpers
658
659
  * are a fixed contract (src/gl/shaders.ts; names are only ever added):
659
- * vertex.head / vertex.main (change `pos`, px offset in the element's own axes, using `uv`)
660
+ * vertex.head / vertex.main (change `pos`, px offset in the element's own axes, using `uv`;
661
+ * every uniform is declared there too, textures included: textureLod(uMap, at, 0.0))
660
662
  * fragment.head / uv / color (vec4) / alpha (float)
661
663
  * inputs: vUv, uSize, uViewport, uRect, uMouse, uTime, uScrollVelocity, uProgress,
662
664
  * uPlaneMatrix (mat3: own px -> viewport px; a translation when flat),
663
- * uSurface (vec4: where this draw goes, viewport px x, y, w, h; today the
664
- * canvas: 0, 0, uViewport), uBleed (px the quad reaches past the element:
665
- * the `bleed` option; vUv then runs below 0 and above 1 there);
666
- * fragment only: uAlpha, uDpr, uImage, uImageSize, uCanvas
665
+ * uSurface (vec4: where this draw goes, viewport px x, y, w, h: the canvas,
666
+ * 0, 0, uViewport, or the window of a group's texture or a snapshot, with a
667
+ * negative height), uBleed (vec4: px the quad reaches past the element at its
668
+ * top, right, bottom and left: the `bleed` option; vUv then runs below 0 and
669
+ * above 1 there), PI;
670
+ * fragment only: uAlpha, uDpr, uImage, uImageSize, uCanvas;
671
+ * a new picture (fragment only): uSwap (0 -> 1 once a new src is on the GPU),
672
+ * samplePrev(uv) (the picture before it, added when called)
667
673
  * a rotated, skewed or 3D-tilted element: vUv, uMouse and `pos` follow its own edges;
668
674
  * uSize is its layout size at its on-screen scale; uRect = centre - uSize / 2, uSize
669
675
  * helpers, fragment only: sampleImage(uv), sampleRaw(uv) (premultiplied: what a blur
@@ -676,13 +682,20 @@ export interface EffectContext<O extends OptionDefaults = OptionDefaults> {
676
682
  * rotate2d(angle), umberHash(vec2 | vec3), glyph(uv), screenPx() (fragment
677
683
  * only: this pixel on screen, viewport CSS px, whatever turns the element),
678
684
  * screenUv() (fragment only: this pixel on screen, 0..1 over the viewport,
679
- * y down), uScreen (vec2: the element's centre on the viewport, -1..1, y down)
685
+ * y down), screenPx(uv) / screenUv(uv) (vertex only: where the element's own uv
686
+ * is on screen), uScreen (vec2: the element's centre on the viewport, -1..1,
687
+ * y down), textureSmooth(tex, uv) (tex through a cubic B-spline over 16 texels:
688
+ * no texel steps in a small field's slopes; textureSmooth(tex, uv, dx, dy) also
689
+ * writes its slope per unit of uv into your vec4s), flowSmooth(uv) and
690
+ * flowSmooth(uv, dx, dy) (uFlow that way)
680
691
  * #include "name" on a line of its own, in any slot: the umber.chunk() of that name, added
681
- * once per program (only included chunks are compiled)
692
+ * once per program (only included chunks are compiled); what a chunk names
693
+ * (uFlow, a helper) counts as the effect's own, on a plane and in a data-umber-pass
682
694
  * two effects on one plane that declare the same top-level name in their heads (a
683
695
  * function, const, global or #define) each get their own (renamed e<N>_name)
684
696
  * glyph(uv), GL text: Glyph { float line, word, char, lines, words, chars;
685
- * vec4 lineBox, wordBox, charBox (x, y, width, height in uv); float ink }
697
+ * vec4 lineBox, wordBox, charBox (x, y, width, height in uv); float ink;
698
+ * vec4 lineValue, wordValue, charValue (plane.text's t, x, y, z; 0 until set) }
686
699
  * after the alpha slot, Umber cuts the plane where its parents cut it in the DOM
687
700
  * (overflow, clip-path); names starting with uUmber / umber are reserved
688
701
  */
@@ -710,10 +723,18 @@ export interface EffectDef<O extends OptionDefaults = OptionDefaults> {
710
723
  * ({ color: "#fff" }) so every element has the vec4. A string with a "/" is an image
711
724
  * path -> sampler2D (a per-element map: data-umber-depth-map="/img/a-depth.webp" ->
712
725
  * uDepthMap; give it a default path). `bleed` (px) draws the plane that much past its
713
- * element on every side (uBleed: the largest of its effects).
726
+ * element on every side; four numbers ("0 0 560 0" or [0, 0, 560, 0]) are its top, right,
727
+ * bottom and left (uBleed, a vec4: per side the largest of its effects). `reach` (px, one
728
+ * number or [top, right, bottom, left]) is the same room round each letter of a
729
+ * data-umber-instances="chars" text, past the letter's ink. `perspective` (px
730
+ * from the eye to the plane) draws what vertex.main moves along pos.z in perspective, about
731
+ * `perspectiveOrigin` (vec2, px in the element's own space; its centre unless vertex.main
732
+ * sets it): pos.z below 0 goes back, as CSS translateZ. At pos.z 0 nothing moves.
714
733
  * setup() and update() read them as ctx.options, typed from these defaults.
715
734
  * @example options: { strength: 1, duration: 1.2, ease: "expo.out" }
716
735
  * @example options: { map: "/img/blank.webp", bleed: 40 }
736
+ * @example options: { bleed: "0 0 560 0" } // only below: an effect that drops its element
737
+ * @example options: { perspective: 800 }
717
738
  */
718
739
  options?: O;
719
740
  /**
@@ -725,12 +746,14 @@ export interface EffectDef<O extends OptionDefaults = OptionDefaults> {
725
746
  /**
726
747
  * A uniform Umber plays 0 -> 1 by itself, with the trigger options every playable
727
748
  * effect understands: trigger (auto | scroll | load | manual | hover), delay, duration, ease,
728
- * start ("top 90%"), repeat ("" once | "reverse" | "true": again each time it scrolls in).
749
+ * start ("top 90%"), repeat ("" once | "reverse" | "true": again each time it scrolls in),
750
+ * hide (true: the element is hidden while GL loads; false: its plain DOM shows until GL has drawn it).
729
751
  * @example play: "uShow"
730
752
  */
731
753
  play?: string;
732
754
  /**
733
- * Grid segments per side: more than 1 when vertex.main bends the plane.
755
+ * Grid segments per side: more than 1 when vertex.main bends the plane (24 is plenty for a
756
+ * bend; a dent a few dozen px wide wants 48).
734
757
  * @default 1
735
758
  */
736
759
  segments?: number;
@@ -742,7 +765,10 @@ export interface EffectDef<O extends OptionDefaults = OptionDefaults> {
742
765
  * "tiles 24x16" one quad per tile: `tile` (vec4 column, row, columns, rows),
743
766
  * `tileCenter` (vec2, uv); move tiles apart with `pos`
744
767
  * "chars" | "words" | "lines" GL text, one quad per unit: `unitValue` (vec4: its t, x, y, z from
745
- * plane.text, what GSAP writes; .x is t), `unitBox` (vec4, its box in uv)
768
+ * plane.text, what a tween writes; .x is t), `unitBox` (vec4, its box in uv).
769
+ * "chars" draws each letter's quad round its ink, from that letter alone:
770
+ * `unitInk` (vec4, its ink box in uv), and in vertex.main `unitScale`,
771
+ * `unitTurn` (radians) and `unitAlpha` to write (at 0 the letter is not drawn)
746
772
  * "echo 6" ("echo 6 delay 0.05") 5 copies where the plane was 0.05 s, 0.1 s... ago (a trail):
747
773
  * `echoOffset` (vec2 px); instance 0 is the plane, drawn on top;
748
774
  * copies that caught up are not drawn
@@ -945,8 +971,9 @@ export interface ProgressSignal extends Signal {
945
971
  readonly destroyed: boolean;
946
972
  on(event: "change" | "destroy", fn: (p: ProgressSignal) => void): () => void;
947
973
  off(event: "change" | "destroy", fn: (p: ProgressSignal) => void): void;
948
- /** Automatic when el leaves the page. */
974
+ /** Automatic when el leaves the page. With `css`, the variable keeps its last value while el is on the page. */
949
975
  destroy(): void;
976
+ /** As destroy(), and with `css` the variable is taken off el. */
950
977
  revert(): void;
951
978
  }
952
979
 
@@ -964,14 +991,14 @@ export interface PointerSignal {
964
991
  readonly active: boolean;
965
992
  }
966
993
 
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";
994
+ /** What a scope makes with the engine's own calls (s.add...), and the definitions and other calls it carries as they are. */
995
+ type ScopeMakes = "add" | "track" | "progress" | "view" | "target" | "snapshot" | "sim" | "flow" | "brush";
969
996
  type ScopeCarries =
970
997
  "effect" | "shader" | "layer" | "chunk" | "on" | "nextFrame" | "scope" | "preload" | "warm" | "leave" | "flip";
971
998
 
972
999
  /**
973
1000
  * umber.scope(fn, container): everything Umber made inside fn, undone with revert(). The
974
- * scope has gl's creating methods: after an await, call them on the scope (s.add, s.track...).
1001
+ * scope has the engine's creating methods: after an await, call them on the scope (s.add, s.track...).
975
1002
  * An add-on's methods join them (types/input.d.ts: s.drag, s.texture...). On revert():
976
1003
  * targets, snapshots, sims and brushes are released (the shared umber.flow() flowmap only when
977
1004
  * this scope's call made it and no plane reads uFlow; options a scope set on it stay);
@@ -992,25 +1019,15 @@ export interface Scope extends Pick<Umber, ScopeMakes | ScopeCarries> {
992
1019
  destroy(): void;
993
1020
  }
994
1021
 
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
- */
999
- export interface ThreeRendererLike {
1000
- domElement?: HTMLCanvasElement;
1022
+ /** What Umber sets and calls on the one renderer umber.renderer(THREE) makes on its canvas. */
1023
+ export interface SharedRendererLike extends LayerRendererLike {
1001
1024
  setSize?(width: number, height: number, updateStyle?: boolean): void;
1002
1025
  setPixelRatio?(ratio: number): void;
1003
- /** The default render(): renderer.render(scene, camera), with the scene and camera you passed. */
1004
- render?(scene: unknown, camera: unknown): void;
1005
- getContext?(): WebGLRenderingContext | WebGL2RenderingContext;
1006
1026
  dispose?(): void;
1007
- }
1008
-
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
1027
  /** The default render(): renderer.render(scene, camera), with the view's scene and camera. */
1013
1028
  render(scene: unknown, camera: unknown): void;
1029
+ /** three.js's own: the scene's shaders compiled, resolved when they are ready. A view waits for it before its first draw. */
1030
+ compileAsync?(scene: unknown, camera: unknown): Promise<unknown>;
1014
1031
  }
1015
1032
 
1016
1033
  /** What umber.renderer(THREE) needs of the three.js module: its WebGLRenderer, made on Umber's canvas and context. */
@@ -1091,21 +1108,6 @@ export interface ViewOptions<
1091
1108
  aspect?: boolean;
1092
1109
  }
1093
1110
 
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> {
1099
- /** Your THREE.WebGLRenderer. Its canvas goes into the element unless it is in the page already. */
1100
- renderer: R;
1101
- /** Max drawing pixels (w * h * dpr^2). @default the engine's pixelBudget, else 12e6 */
1102
- pixelBudget?: number;
1103
- /** Lower the resolution only when frames get slow. @default the engine's adaptive */
1104
- adaptive?: boolean;
1105
- /** renderer.dispose() and free its WebGL context when the view goes. false for a renderer you reuse. @default true */
1106
- dispose?: boolean;
1107
- }
1108
-
1109
1111
  /** `R`: the renderer umber.renderer(THREE) made (null in the callbacks until it resolved). */
1110
1112
  export interface SharedViewOptions<
1111
1113
  S = unknown,
@@ -1123,10 +1125,9 @@ export interface SharedViewOptions<
1123
1125
  export type ViewStatus = "loading" | "ready" | "off" | "error" | "lost" | "destroyed";
1124
1126
  export type ViewEvent = "ready" | "resize" | "enter" | "leave" | "lost" | "restored" | "error" | "destroy";
1125
1127
 
1126
- /** umber.attach() / umber.view(): your three.js scene tied to an element. */
1128
+ /** umber.view(): your three.js scene tied to an element. */
1127
1129
  export interface View {
1128
1130
  readonly el: HTMLElement;
1129
- readonly kind: "attach" | "view";
1130
1131
  readonly status: ViewStatus;
1131
1132
  /** false when it is not drawn on this device, failed, or was destroyed. */
1132
1133
  readonly enabled: boolean;
@@ -1210,21 +1211,8 @@ export interface ScreenPoint {
1210
1211
  visible: boolean;
1211
1212
  }
1212
1213
 
1213
- /** Pure helpers: Umber.math, or named imports from the npm package. `frame` = the canvas box in viewport px (default: the viewport). */
1214
+ /** Pure helpers: Umber.math, or named imports from the npm package. */
1214
1215
  export interface UmberMath {
1215
- /** CSS px per world unit at `distance` (default: the camera's distance to z = 0) on a picture `heightPx` tall (default: the viewport). */
1216
- pxPerWorld(camera: CameraLike, distance?: number, heightPx?: number): number;
1217
- /** Aim the camera so it sees exactly `size` at z = 0, `unit` CSS px per world unit (default 1). */
1218
- fitCamera<C extends CameraLike>(camera: C, size: { width: number; height: number }, unit?: number): C;
1219
- /** A DOM rect's centre on the plane z (default 0) and its size there; writes x, y, z into `out`. */
1220
- rectToWorld(
1221
- rect: RectLike,
1222
- camera: CameraLike,
1223
- out?: Partial<Vec3Like> | null,
1224
- options?: { z?: number; frame?: RectLike },
1225
- ): WorldBox;
1226
- /** A world point in viewport CSS px. */
1227
- worldToRect(point: Vec3Like, camera: CameraLike, frame?: RectLike): ScreenPoint;
1228
1216
  /** Lerp that feels the same at 60, 120 and 144 Hz: damp(current, target, 0.1, f.dt). */
1229
1217
  damp(current: number, target: number, amount: number, dt: number): number;
1230
1218
  clamp(v: number, min?: number, max?: number): number;
@@ -1244,10 +1232,12 @@ export interface UmberMath {
1244
1232
  ): number;
1245
1233
  }
1246
1234
 
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). */
1235
+ /** umber.on(name, fn): what each event hands fn. Each but "frame" and "step" also goes to document as a DOM event, "umber:<name>" (payload in detail). */
1248
1236
  export interface UmberEvents {
1249
1237
  /** Every frame the loop runs (umber.on("frame") adds fn to the loop). */
1250
1238
  frame: Frame;
1239
+ /** Every frame the loop runs, first: before Umber reads the page (umber.on("step") adds fn to the loop). */
1240
+ step: Frame;
1251
1241
  /** GL draws this page's [data-umber] elements: the engine. */
1252
1242
  ready: Umber;
1253
1243
  /** The WebGL context was lost. */
@@ -1288,16 +1278,21 @@ export interface Umber {
1288
1278
  */
1289
1279
  readonly pointer: PointerSignal;
1290
1280
  /**
1291
- * An event (UmberEvents says what fn gets), or "frame": fn joins the loop. Returns off().
1292
- * A "frame" callback keeps the loop running every frame; { always: false } only rides
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).
1281
+ * An event (UmberEvents says what fn gets), or "frame" or "step": fn joins the loop.
1282
+ * Returns off(). A "frame" callback keeps the loop running every frame; { always: false }
1283
+ * only rides along on frames Umber runs anyway. "step" is the place to step a scroller of
1284
+ * your own: it runs every frame before Umber reads the page, and Umber measures and draws
1285
+ * only in the frames it moved the page in. The other events are also sent on document as
1286
+ * DOM events (umber:ready, umber:off...; payload in detail).
1295
1287
  * @example const off = umber.on("frame", (f) => { mesh.rotation.y += f.dt; }, { phase: "update" });
1288
+ * @example umber.on("step", (f) => scroller.step(f.dt));
1296
1289
  * @example umber.on("fallback", ({ el, reason }) => analytics.track("umber-fallback", { reason }));
1297
1290
  * @example document.addEventListener("umber:ready", (e) => console.log(e.detail));
1298
1291
  */
1299
- on(name: "frame", fn: (frame: Frame) => void, opts?: FrameOptions): () => void;
1292
+ on(name: "frame", fn: (frame: Frame, off: () => void) => void, opts?: FrameOptions): () => void;
1293
+ on(name: "step", fn: (frame: Frame, off: () => void) => void, opts?: StepOptions): () => void;
1300
1294
  on<E extends keyof UmberEvents>(name: E, fn: (payload: UmberEvents[E]) => void): () => void;
1295
+ off(name: "frame" | "step", fn: (frame: Frame, off: () => void) => void): void;
1301
1296
  off<E extends keyof UmberEvents>(name: E, fn: (payload: UmberEvents[E]) => void): void;
1302
1297
  /** `O`: the option defaults, which type ctx.options in setup() and update(). */
1303
1298
  effect<O extends OptionDefaults>(name: string, def: EffectDef<O>): void;
@@ -1321,9 +1316,11 @@ export interface Umber {
1321
1316
  use(module: UmberModule, options?: Record<string, unknown>): Umber;
1322
1317
  /**
1323
1318
  * Whether this page's domain is on an Umber licence (the domains listed at occluze.com).
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.
1319
+ * Asked once per page, by GL or any add-on, and nothing waits
1320
+ * for it: Umber runs at once, and a site that isn't licensed runs with a small Occluze badge.
1321
+ * Yes on your own computer and network (localhost, *.localhost, *.test, a private IP address); no when the check can't be reached:
1322
+ * only a clear yes counts. A site Occluze blocked loses GL (umber.reason "blocked"), as does a page
1323
+ * that keeps removing or hiding the badge.
1327
1324
  */
1328
1325
  licensed(): Promise<boolean>;
1329
1326
  /** umber.licensed()'s answer once it is in; null while it is asked (or before anything asked). */
@@ -1344,8 +1341,8 @@ export interface Umber {
1344
1341
  */
1345
1342
  scope(fn?: (scope: Scope) => unknown, container?: string | Element | null): Scope;
1346
1343
  /**
1347
- * A live 0..1 as el scrolls from `start` to `end`, from the measure phase (native
1348
- * scroll, a scroll container or Lenis alike; also with GL off). Usable as a uniform.
1344
+ * A live 0..1 as el scrolls from `start` to `end`, from the measure phase (the window,
1345
+ * a scroll container, under any scroller; also with GL off). Usable as a uniform.
1349
1346
  * Ends when el leaves the page.
1350
1347
  * @example umber.effect("story", { uniforms: { uStory: umber.progress(".story", { start: "top top", end: "bottom bottom" }) } })
1351
1348
  */
@@ -1384,8 +1381,6 @@ export interface Umber {
1384
1381
  planes(container?: ParentNode): Plane[];
1385
1382
  /** Hold every play back. Returns release(delaySeconds?); hold(promise) releases when it settles. */
1386
1383
  hold(until?: PromiseLike<unknown>): (delay?: number) => void;
1387
- /** One frame from your own loop (with loop: false). time in ms, like requestAnimationFrame. */
1388
- render(time?: number): void;
1389
1384
  /**
1390
1385
  * A page change, for any router: call it in the hook where a change starts, and the
1391
1386
  * function it returns in the hook where it is done. Plays are held and planes measured
@@ -1397,15 +1392,20 @@ export interface Umber {
1397
1392
  * next: the next page when the router has it (HTML, a parsed Document, its container,
1398
1393
  * or a promise of one): a matching image freezes at once instead of fading with its page.
1399
1394
  *
1395
+ * options: { leaving } names the container that goes while both pages are in the
1396
+ * document (GL draws none of it from then on: its elements show their DOM); { timeout }
1397
+ * gives a change more than 8 s.
1398
+ *
1400
1399
  * end(after?): after = seconds before plays start, or a promise (a View Transition's
1401
1400
  * `finished`). Resolves once the image landed and the new page's planes on screen draw
1402
1401
  * (4 s at most), so a router hook can await it.
1403
1402
  * @example let end = () => {};
1404
- * swup.hooks.on("visit:start", () => (end = umber.transition()));
1405
- * swup.hooks.on("page:load", (visit, { page }) => umber.transition(page.html)); // Swup 4
1406
- * swup.hooks.on("visit:end", () => end());
1403
+ * router.on("start", () => (end = umber.transition()));
1404
+ * router.on("loaded", (page) => umber.transition(page.html));
1405
+ * router.on("end", () => end());
1406
+ * @example umber.transition(next.container, { leaving: current.container, timeout: 20 });
1407
1407
  */
1408
- transition(next?: NextPage): (after?: number | PromiseLike<unknown>) => Promise<void>;
1408
+ transition(next?: NextPage, options?: TransitionOptions): (after?: number | PromiseLike<unknown>) => Promise<void>;
1409
1409
  /**
1410
1410
  * The page-change look (chunks/fx.js): on every page change, a copy of the old page's
1411
1411
  * GL is laid over the new page and your GLSL takes it away. Define
@@ -1431,22 +1431,13 @@ export interface Umber {
1431
1431
  * The lower-level parts of umber.transition() for data-umber-id flights. capture(next): a
1432
1432
  * navigation starts; when the next page is known the matching image freezes where it is
1433
1433
  * ("" or nothing = not known yet). settle(): the swap is done.
1434
- * @example barba.hooks.before((data) => umber.morph.capture(data.next.html)); barba.hooks.after(() => umber.morph.settle());
1434
+ * @example router.on("leave", (next) => umber.morph.capture(next.html)); router.on("done", () => umber.morph.settle());
1435
1435
  */
1436
1436
  morph: { capture(next?: NextPage): void; settle(): void };
1437
1437
  /** Where an element is, every frame, without WebGL (works with GL off). Ends when el leaves the page. */
1438
1438
  track(el: string | Element, options?: TrackOptions): Tracker;
1439
1439
  /**
1440
- * Your three.js scene in its own canvas (the drop-in mode). Umber sizes the renderer,
1441
- * draws only while el is on screen and something asked, and cleans up when el leaves.
1442
- * @example umber.attach(el, { renderer, scene, camera, devices: "all", animate: (f) => { mesh.rotation.y += f.dt; return true; } })
1443
- */
1444
- attach<S, C extends ViewCameraLike | undefined, R extends ThreeRendererLike>(
1445
- el: string | Element,
1446
- options: AttachOptions<S, C, R>,
1447
- ): View;
1448
- /**
1449
- * Advanced: a scene drawn into Umber's own canvas, next to the DOM planes, with the one
1440
+ * A scene drawn into Umber's own canvas, next to the DOM planes, with the one
1450
1441
  * renderer from umber.renderer(THREE). Clipped to el, fades with it, goes when el leaves.
1451
1442
  * @example const renderer = await umber.renderer(THREE); umber.view(el, { scene, camera });
1452
1443
  */
@@ -1507,18 +1498,21 @@ export interface Umber {
1507
1498
  brush(sim: Sim | null, options?: BrushOptions): Brush | null;
1508
1499
  /**
1509
1500
  * Get the NEXT page ready before it is on the page (its own file, chunks/warm.js): the
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
1512
- * programs compiled, and each drawn once offscreen. When the elements arrive they claim
1513
- * all of it: the first frame does no work. Never blocks the page (uploads go in idle
1514
- * moments) and never rejects. The promise is also the progress: p.value 0 -> 1, a Signal
1515
- * (fn(v) hears each step). With GL off it resolves at once with value 1.
1501
+ * images its first screen's [data-umber] elements show fetched, decoded and on the GPU
1502
+ * (keyed the way the element will ask: data-umber-src, or the srcset candidate the browser
1503
+ * will pick), every element's program compiled, and each drawn once offscreen. When the
1504
+ * elements arrive they claim all of it: the first frame does no work. The first screen is
1505
+ * the pictures that come first in the page, until their boxes (sizes, width and height)
1506
+ * would fill the screen; the rest load as they come near, as on any page. Nothing is put
1507
+ * on the GPU past its memory budget. Never blocks the page (uploads go in idle moments)
1508
+ * and never rejects. The promise is also the progress: p.value 0 -> 1, a Signal (fn(v)
1509
+ * hears each step). With GL off it resolves at once with value 1.
1516
1510
  *
1517
1511
  * what: image URLs, a page URL (fetched and read), an element or container (detached is
1518
- * fine), a parsed Document, Barba's data.next ({ container } / { html } / { url }), or a
1519
- * list of these. { hover: true | "selector" }: from now on, a link's page is preloaded
1512
+ * fine), a parsed Document, a router's next page ({ container } / { html } / { url }), or
1513
+ * a list of these. { hover: true | "selector" }: from now on, a link's page is preloaded
1520
1514
  * when the pointer slows down over it (off on Save-Data; { hover: false } stops it).
1521
- * @example barba.hooks.leave((data) => { umber.preload(data.next.url.href); }); // braces: Barba waits for a returned promise
1515
+ * @example router.on("leave", (next) => { umber.preload(next.url); });
1522
1516
  * @example umber.preload({ hover: "a.project-link" });
1523
1517
  */
1524
1518
  preload(
@@ -1555,7 +1549,7 @@ export interface GpuInfo {
1555
1549
  /** "rule: <what matched>", "default" or "url" (?umber-gpu). */
1556
1550
  reason: string;
1557
1551
  maxTexture: number;
1558
- /** Max bytes of image textures kept on the GPU. */
1552
+ /** Max bytes of image textures kept on the GPU: the one in use now (a desktop's grows the first time a page fills it). */
1559
1553
  textureBudget: number;
1560
1554
  /** Above this CSS width the canvas DPR is cut (createUmber dpr aside); Infinity: never. */
1561
1555
  wide: number;
@@ -1681,7 +1675,10 @@ export interface Target {
1681
1675
  * `vec4 color(vec2 uv)` (straight alpha: Umber premultiplies), or its own `void main()`
1682
1676
  * writing `outColor` (premultiplied; more attachments: layout(location = 1) out vec4 ...).
1683
1677
  * Built in: vUv, uSize (device px), uTime. Uniforms are declared for you; a target or a
1684
- * texture holder is a sampler. Drawn again after a resize and a restored context.
1678
+ * texture holder is a sampler, a CSS colour string a vec4, and any other string a picture's
1679
+ * address: a sampler, and the pass is drawn once every picture it reads has loaded. Drawn
1680
+ * again after a resize and a restored context.
1681
+ * @example target.draw("vec4 color(vec2 uv) { return texture(uPortrait, uv); }", { uPortrait: "/img/portrait.webp" });
1685
1682
  */
1686
1683
  draw(glsl: string, uniforms?: Record<string, unknown>): Target;
1687
1684
  /** Transparent again. */
package/types/vite.d.ts CHANGED
@@ -1,13 +1,13 @@
1
1
  /**
2
2
  * `@occluze/umber/vite`: prepares the pictures Umber draws after `vite build` (see
3
3
  * `@occluze/umber/assets`), and puts Umber's chunks in the built site, so they load from its own
4
- * origin. `vite dev` is left alone.
4
+ * origin. In `vite dev` the dev server serves the same chunks from the installed package.
5
5
  *
6
6
  * import umberAssets from "@occluze/umber/vite";
7
7
  * export default { plugins: [umberAssets()] };
8
8
  */
9
9
 
10
- import type { SiteOptions } from "./assets";
10
+ import type { SiteOptions } from "./assets.js";
11
11
 
12
12
  /**
13
13
  * prepareSite()'s options (the folder and base URL come from Vite's config), whether to minify the
@@ -26,7 +26,7 @@ export interface UmberVitePlugin {
26
26
  * The plugins: one prepares the pictures (and fonts) after the build, one minifies the GLSL
27
27
  * of the site's effects (their `fragment` and `vertex` parts, and literals marked
28
28
  * `/* glsl *\/`) while it bundles, and one writes Umber's chunks into the site
29
- * (`<assets>/umber@<version>/chunks/`) and points the bundled engine at them, so the built site
29
+ * (`<assets>/umber-<version>/chunks/`) and points the bundled engine at them, so the built site
30
30
  * loads nothing from umber.occluze.com but the licence check. `shaders: false` leaves the second
31
31
  * out, `chunks: false` the third. createUmber({ base }) and window.UmberConfig.base still win.
32
32
  */