@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/docs/npm.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Umber as an npm package
2
2
 
3
- For bundled sites (Astro, Vite, Next.js) Umber is also an npm package, `@occluze/umber`, on the public npm registry. It is the same engine as `umber.js`, built as an ES module (`dist/umber.mjs`). Webflow sites keep the `<script>` tag ([hosting.md](hosting.md)); nothing changes for them.
3
+ For bundled sites (Astro, Vite, Next.js) Umber is the npm package `@occluze/umber`, on the public npm registry. It is the same engine as `umber.js`, built as an ES module (`dist/umber.mjs`), and it brings the build tool: the Vite plugin, the Astro integration and the `umber assets` command ([the build tool](ai/assets.md)). A site without a build step uses the `<script>` tag ([getting started](getting-started.md)).
4
4
 
5
5
  ## Install
6
6
 
@@ -10,49 +10,47 @@ Install the version you want, exactly:
10
10
  npm install --save-exact @occluze/umber@0.3.0 # nothing changes under the site until you change this number
11
11
  ```
12
12
 
13
- No token or `.npmrc` is needed. What licenses it is your account's public key, from [occluze.com/dashboard?view=umber](https://occluze.com/dashboard?view=umber): pass it as `createUmber({ key: "YOUR_KEY" })`, and publish. While your account is on Approve automatically (the first 30 minutes after buying, or 30 minutes whenever you switch it on in the dashboard) it joins your domains and runs on the next refresh; on Block all, nothing new gets in. Your own computer and network need no key ([hosting.md](hosting.md)).
13
+ No token or `.npmrc` is needed. What licenses it is your account's public key, from [occluze.com/dashboard?view=umber](https://occluze.com/dashboard?view=umber): pass it as `createUmber({ key: "YOUR_KEY" })`. Umber runs at once either way; a site that is not on the account yet runs with a small Occluze badge until it is. Your own computer and network need no key ([hosting and the licence](hosting.md)).
14
14
 
15
15
  ## Use it
16
16
 
17
17
  <!-- snippet:npm -->
18
18
  ```js
19
- // npm install @occluze/umber@0.3.0 (docs/npm.md)
19
+ // npm install --save-exact @occluze/umber@0.4.1
20
20
  import { createUmber } from "@occluze/umber";
21
21
  import "@occluze/umber/umber.css";
22
- import { Scroll } from "@occluze/umber/scroll"; // smooth scrolling, on Umber's clock
23
- import { Router } from "@occluze/umber/router"; // page transitions without a reload
24
22
 
25
- const umber = createUmber({ key: "YOUR_KEY", modules: [Scroll, Router] }); // client code only; on the server it does nothing
23
+ const umber = createUmber({ key: "YOUR_KEY" }); // browser code only; on a server it does nothing
24
+ // An effect is yours to write: a name, and a few lines of GLSL in named slots.
25
+ umber.effect("fade", { play: "uShow", uniforms: { uShow: 0 }, fragment: { alpha: "alpha *= uShow;" } });
26
26
  ```
27
27
  <!-- /snippet -->
28
28
 
29
29
  ```js
30
30
  // src/site.js (runs in the browser). Your libraries stay yours: Umber never imports them.
31
- import Lenis from "lenis";
32
- import barba from "@barba/core";
31
+ import "./scroller.js"; // your smooth scroller, set up as its docs say
32
+ import "./router.js"; // your router, the same
33
33
  import { createUmber } from "@occluze/umber";
34
34
  import { Debug } from "@occluze/umber/debug"; // while you build only
35
35
  import { dissolve } from "./gl/effects.js"; // your own effects
36
36
 
37
- const lenis = new Lenis({ autoRaf: true });
38
- const umber = createUmber({ scroll: lenis, modules: import.meta.env.DEV ? [Debug] : [] });
37
+ const umber = createUmber({ modules: import.meta.env.DEV ? [Debug] : [] }); // nothing of the scroller or the router is passed
39
38
  umber.effect("dissolve", dissolve);
40
- barba.init({ /* your transitions */ });
41
39
  ```
42
40
 
43
- - **Exports:** `.` (`createUmber`, `version`, `math` and the maths as named exports: `rectToWorld`, `worldToRect`, `pxPerWorld`, `fitCamera`, `damp`, `clamp`, `lerp`, `mapRange`, `smoothstep`, `rectProgress`), `./scrub` (`Scrub`), `./debug` (`Debug`, `debug`), `./input` (`Input`, `input`), `./handoff` (`Handoff`, `handoff`; `Handoff.headSnippet`), `./scroll` (`Scroll`, `smoothScroll`; with `touch: true` its second file, `dist/modules/scroll-touch.js`, is `import()`ed from it), `./scrollfx` (`ScrollFx`), `./router` (`Router`, `router`; its second file, `dist/modules/router-swap.js`, is `import()`ed from it, so your bundler splits it off), `./three` (`Three`, `addThree`; three.js is an optional peer dependency it `import()`s by name, so your bundler splits it off and pages without 3D never load it), `./umber.css`, `./umber.js` (the script build, sets `window.Umber`). Types are included for all of them (`import type { GL, UmberOptions, EffectDef } from "@occluze/umber"`). An import gets no `window.Umber` type, since the npm build never sets it; a site that loads `umber.js` with a tag adds `/// <reference types="@occluze/umber/global" />`.
41
+ - **Exports:** `.` (`createUmber`, `version`, `math` and the maths as named exports: `damp`, `clamp`, `lerp`, `mapRange`, `smoothstep`, `rectProgress`), `./scrub` (`Scrub`), `./debug` (`Debug`, `debug`), `./input` (`Input`, `input`), `./handoff` (`Handoff`, `handoff`; `Handoff.headSnippet`), `./scrollfx` (`ScrollFx`), `./three` (`Three`, `addThree`; three.js is an optional peer dependency it `import()`s by name, so your bundler splits it off and pages without 3D never load it), `./umber.css`, `./umber.js` (the script build, sets `window.Umber`). Types are included for all of them (`import type { GL, UmberOptions, EffectDef } from "@occluze/umber"`). An import gets no `window.Umber` type, since the npm build never sets it; a site that loads `umber.js` with a tag adds `/// <reference types="@occluze/umber/global" />`.
44
42
  - **Nothing runs on import.** Importing in server-rendered files (Astro frontmatter, a Next.js component) is safe; on the server `createUmber()` returns an engine that does nothing (`umber.enabled` false, `umber.reason` `"server"`). Call it from code that runs in the browser (Astro: a `<script>`; Next.js: `useEffect` or a client-only module).
45
43
  - **One engine per page.** When a `umber.js` `<script>` already started an engine, `createUmber()` returns that one (with a warning) instead of starting a second.
46
44
  - **No effects ship in the package.** You write them with `umber.effect()` ("Writing effects" in [AI.md](AI.md)).
47
45
 
48
46
  ## Where the chunks come from
49
47
 
50
- The GL runtime (`chunks/gl.js`) and its other chunks (`chunks/*.js`: shapes, text, layers, morph, video, fx, warm, views... each only when a page needs it) load on demand, at the exact version of the package. The files can be served from anywhere: the licence check (`chunks/licence.js`, which always asks `umber.occluze.com`) decides from your key and the hostname whether GL starts on this site.
48
+ The GL runtime (`chunks/gl.js`) and its other chunks (`chunks/*.js`: shapes, text, layers, morph, video, fx, warm, views... each only when a page needs it) load on demand, at the exact version of the package. The files can be served from anywhere: the licence check (`chunks/licence.js`, which always asks `umber.occluze.com`) tells from your key and the hostname whether this site is licensed. GL starts without waiting for it; a site that isn't licensed runs with a small Occluze badge.
51
49
 
52
- - **Built with the Vite plugin or the Astro integration** (`@occluze/umber/vite`, `@occluze/umber/astro`, the same ones that prepare your pictures): from your own site. `vite build` and `astro build` copy the package's chunks to `<assets>/umber@<version>/chunks/` in the output (`assets/` for Vite, `_astro/` for Astro) and point the engine at them, with your `base` taken into account. Nothing to set, and a strict `script-src 'self'` works ([Content Security Policy](hosting.md#content-security-policy)). `vite dev` and `astro dev` load them from the CDN. `umberAssets({ chunks: false })` / `umberAstro({ chunks: false })` keeps the CDN for the build too. The version is in the folder's name, so a host may cache it forever:
50
+ - **Built with the Vite plugin or the Astro integration** (`@occluze/umber/vite`, `@occluze/umber/astro`, the same ones that prepare your pictures): from your own site. `vite build` and `astro build` copy the package's chunks to `<assets>/umber-<version>/chunks/` in the output (`assets/` for Vite, `_astro/` for Astro) and point the engine at them, with your `base` taken into account. Nothing to set, and a strict `script-src 'self'` works ([Content Security Policy](hosting.md#content-security-policy)). `vite dev` and `astro dev` serve the same files from the dev server (`<base>__umber/<version>/chunks/`, straight from the installed package), so dev and build run the same chunks and neither needs the CDN. `umberAssets({ chunks: false })` / `umberAstro({ chunks: false })` keeps the CDN for the build too. The version is in the folder's name, so a host may cache it forever:
53
51
 
54
52
  ```
55
- /assets/umber@*
53
+ /assets/umber-*
56
54
  Cache-Control: public, max-age=31536000, immutable
57
55
  ```
58
56
 
@@ -77,4 +75,3 @@ The GL runtime (`chunks/gl.js`) and its other chunks (`chunks/*.js`: shapes, tex
77
75
  - **The code is public once a site uses it**, as with any front-end code: anyone can read the files a page loads. Your key and the sites you approve are what license Umber; the files ship minified, without source maps.
78
76
  - **The chunks load on demand** (from your site or the CDN, above): when they can't load, the GL runtime does not start (the console says `chunks/gl.js failed to load`) and the plain DOM shows. The engine facade, bundled into the site, keeps running.
79
77
  - **Mixing versions:** the package version and the chunks in a `base` folder must match. A mismatch can load a GL chunk of another version. The plugins always copy the package's own.
80
- - **Publishing** (engine owner, Ravi): `npm publish` sends it to the public npm registry (`publishConfig` in package.json), under the npm organisation **occluze**, which owns the `@occluze` scope. Only the built files in `files` ship: no source and no source maps.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@occluze/umber",
3
- "version": "0.3.0",
3
+ "version": "0.4.1",
4
4
  "description": "Umber: a DOM-to-WebGL engine that works next to the libraries a site already uses and controls none of them. Tag DOM elements; Umber draws them as GPU planes on one canvas, kept in line with the page.",
5
5
  "license": "SEE LICENSE IN LICENSE.md",
6
6
  "homepage": "https://github.com/ravi-klaassens/umber#readme",
@@ -44,50 +44,29 @@
44
44
  "import": "./dist/modules/handoff.mjs",
45
45
  "default": "./dist/modules/handoff.mjs"
46
46
  },
47
- "./scroll": {
48
- "types": "./types/scroll.d.ts",
49
- "import": "./dist/modules/scroll.mjs",
50
- "default": "./dist/modules/scroll.mjs"
51
- },
52
47
  "./scrollfx": {
53
48
  "types": "./types/scrollfx.d.ts",
54
49
  "import": "./dist/modules/scrollfx.mjs",
55
50
  "default": "./dist/modules/scrollfx.mjs"
56
51
  },
57
- "./react": {
58
- "types": "./types/react.d.ts",
59
- "import": "./dist/frameworks/react.mjs",
60
- "default": "./dist/frameworks/react.mjs"
61
- },
62
- "./vue": {
63
- "types": "./types/vue.d.ts",
64
- "import": "./dist/frameworks/vue.mjs",
65
- "default": "./dist/frameworks/vue.mjs"
66
- },
67
- "./svelte": {
68
- "types": "./types/svelte.d.ts",
69
- "import": "./dist/frameworks/svelte.mjs",
70
- "default": "./dist/frameworks/svelte.mjs"
71
- },
72
52
  "./astro": {
73
53
  "types": "./types/astro.d.ts",
74
- "browser": "./dist/frameworks/astro.mjs",
75
- "node": "./dist/node/astro.mjs",
76
- "default": "./dist/frameworks/astro.mjs"
54
+ "import": "./dist/node/astro.mjs",
55
+ "default": "./dist/node/astro.mjs"
77
56
  },
78
57
  "./module": {
79
58
  "types": "./types/module.d.ts"
80
59
  },
81
- "./router": {
82
- "types": "./types/router.d.ts",
83
- "import": "./dist/modules/router.mjs",
84
- "default": "./dist/modules/router.mjs"
85
- },
86
60
  "./three": {
87
61
  "types": "./types/three.d.ts",
88
62
  "import": "./dist/modules/three.mjs",
89
63
  "default": "./dist/modules/three.mjs"
90
64
  },
65
+ "./prepared": {
66
+ "types": "./types/prepared.d.ts",
67
+ "import": "./dist/prepared.mjs",
68
+ "default": "./dist/prepared.mjs"
69
+ },
91
70
  "./umber.css": "./dist/umber.css",
92
71
  "./umber.js": "./dist/umber.js",
93
72
  "./types": {
@@ -110,14 +89,15 @@
110
89
  },
111
90
  "files": [
112
91
  "LICENSE.md",
92
+ "THIRD-PARTY-NOTICES.md",
113
93
  "dist/umber.mjs",
94
+ "dist/prepared.mjs",
114
95
  "dist/umber.js",
115
96
  "dist/umber.css",
116
97
  "dist/chunks/*.js",
117
98
  "dist/chunks/*.wasm",
118
99
  "dist/modules/*.js",
119
100
  "dist/modules/*.mjs",
120
- "dist/frameworks/*.mjs",
121
101
  "dist/node/*.mjs",
122
102
  "types/umber.d.ts",
123
103
  "types/global.d.ts",
@@ -126,13 +106,8 @@
126
106
  "types/debug.d.ts",
127
107
  "types/input.d.ts",
128
108
  "types/handoff.d.ts",
129
- "types/scroll.d.ts",
130
109
  "types/scrollfx.d.ts",
131
- "types/react.d.ts",
132
- "types/vue.d.ts",
133
- "types/svelte.d.ts",
134
110
  "types/astro.d.ts",
135
- "types/router.d.ts",
136
111
  "types/three.d.ts",
137
112
  "types/module.d.ts",
138
113
  "types/loop.d.ts",
@@ -150,9 +125,7 @@
150
125
  "./dist/modules/debug.js",
151
126
  "./dist/modules/input.js",
152
127
  "./dist/modules/handoff.js",
153
- "./dist/modules/scroll.js",
154
128
  "./dist/modules/scrollfx.js",
155
- "./dist/modules/router.js",
156
129
  "./dist/modules/three.js"
157
130
  ],
158
131
  "publishConfig": {
@@ -187,16 +160,21 @@
187
160
  "check:glsl": "node test/browser/glsl.mjs",
188
161
  "check:stress": "node test/browser/stress.mjs",
189
162
  "check:capture": "node test/browser/capture.mjs",
190
- "check:router": "node test/browser/router.mjs",
191
163
  "check:modules": "node test/browser/modules.mjs",
192
164
  "check:fade": "node test/browser/fade.mjs",
165
+ "check:plug": "node test/browser/plug.mjs",
166
+ "check:vertex": "node test/browser/vertex.mjs",
193
167
  "check:clock": "node test/browser/clock.mjs",
168
+ "check:scrollers": "node test/browser/scrollers.mjs",
169
+ "check:routers": "node test/browser/routers.mjs",
194
170
  "check:three": "node test/browser/three.mjs",
195
171
  "check:pictures": "node test/browser/pictures.mjs",
196
172
  "check:licence": "node test/browser/licence.mjs",
197
173
  "check:csp": "node test/browser/csp.mjs",
198
174
  "check:curves": "node test/browser/curves.mjs",
199
175
  "check:tiny": "node test/browser/tiny.mjs",
176
+ "check:scale": "node test/browser/scale.mjs",
177
+ "check:motion": "node test/browser/motion.mjs",
200
178
  "scrub": "node scripts/scrub.mjs",
201
179
  "release": "node deploy/release.mjs",
202
180
  "deploy": "node deploy/deploy.mjs",
@@ -220,6 +198,7 @@
220
198
  "happy-dom": "21.0.4",
221
199
  "knip": "6.44.1",
222
200
  "lenis": "1.3.23",
201
+ "pg": "8.23.1",
223
202
  "pixelmatch": "7.2.0",
224
203
  "playwright": "1.63.0",
225
204
  "prettier": "3.9.10",
@@ -246,13 +225,11 @@
246
225
  "entry": [
247
226
  "src/umber.ts",
248
227
  "src/esm.ts",
228
+ "src/prepared.ts",
249
229
  "src/umber.css",
250
230
  "src/gl/index.ts",
251
- "src/gl/{text,curves,shapes,layers,morph,video,glsl,licence,badge,restore,covers,inspect,fx,sim,basis,instances,warm,flip,capture,profiler,patch,prepared,vocabulary}/index.ts",
252
- "src/views/index.ts",
231
+ "src/gl/{text,curves,shapes,layers,morph,video,glsl,licence,badge,recheck,restore,covers,inspect,fx,sim,basis,instances,warm,flip,capture,profiler,patch,prepared,pace,batches,glyphs,resize,vocabulary}/index.ts",
253
232
  "src/modules/*/{index,from-script}.ts",
254
- "src/frameworks/{react,vue,svelte,astro}.ts",
255
- "src/modules/router/swap.ts",
256
233
  "types/*.d.ts",
257
234
  "scripts/*.mjs",
258
235
  "deploy/*.mjs",
@@ -260,9 +237,16 @@
260
237
  "test/browser/*.mjs",
261
238
  "test/browser/fixtures/*.js",
262
239
  "test/browser/clock/*.js",
240
+ "test/browser/scrollers/*.js",
241
+ "test/browser/routers/*.js",
263
242
  "test/browser/csp/*.js",
264
243
  "test/browser/csp/site/*.js",
265
244
  "test/browser/bench/*.js",
245
+ "test/browser/heavy/*.mjs",
246
+ "test/browser/heavy/lib/effects.mjs",
247
+ "test/browser/heavy/site/*.js",
248
+ "test/browser/rivals/*/*.{mjs,js}",
249
+ "test/browser/rivals/*/site/*.js",
266
250
  "test/dist/*.ts",
267
251
  "tools/assets/{cli,index,vite,astro}.ts"
268
252
  ],
@@ -281,11 +265,11 @@
281
265
  ]
282
266
  },
283
267
  "optionalDependencies": {
284
- "@occluze/umber-assets-win32-x64-msvc": "0.3.0",
285
- "@occluze/umber-assets-win32-arm64-msvc": "0.3.0",
286
- "@occluze/umber-assets-darwin-x64": "0.3.0",
287
- "@occluze/umber-assets-darwin-arm64": "0.3.0",
288
- "@occluze/umber-assets-linux-x64-gnu": "0.3.0",
289
- "@occluze/umber-assets-linux-arm64-gnu": "0.3.0"
268
+ "@occluze/umber-assets-win32-x64-msvc": "0.4.1",
269
+ "@occluze/umber-assets-win32-arm64-msvc": "0.4.1",
270
+ "@occluze/umber-assets-darwin-x64": "0.4.1",
271
+ "@occluze/umber-assets-darwin-arm64": "0.4.1",
272
+ "@occluze/umber-assets-linux-x64-gnu": "0.4.1",
273
+ "@occluze/umber-assets-linux-arm64-gnu": "0.4.1"
290
274
  }
291
275
  }
package/types/assets.d.ts CHANGED
@@ -17,13 +17,44 @@ export interface PrepareOptions {
17
17
  /** The longest side of the largest level, px (4096): a bigger picture is scaled down to it. */
18
18
  maxSize?: number;
19
19
  /**
20
- * The quality floor, dB (40): each GPU file is the smallest (format, ASTC block size,
20
+ * The quality floor, dB (38.75 for an opaque picture, 40 for one with alpha): each GPU file is the smallest (format, ASTC block size,
21
21
  * rate-distortion optimisation) whose largest level stays at least this close to the
22
22
  * picture (PSNR of its colours).
23
23
  */
24
24
  quality?: number;
25
25
  }
26
26
 
27
+ /** What a number file holds: its element type, or "raw" for bytes that are only deflated. */
28
+ export type DataType = "raw" | "u8" | "i8" | "u16" | "i16" | "u32" | "i32" | "f32" | "f64";
29
+
30
+ /** A number file to pack: its path inside the site's folder and what it holds (a bare path: "raw"). */
31
+ export type DataFile = string | { file: string; type: DataType };
32
+
33
+ /** How `encodeVideos` encodes; every field may be left out. */
34
+ /** The parts of an effect's definition the tool reads (`effects`): an `EffectDef` fits. */
35
+ export interface EffectSource {
36
+ vertex?: Record<string, unknown>;
37
+ fragment?: Record<string, unknown>;
38
+ options?: Record<string, unknown>;
39
+ }
40
+
41
+ export interface EncodeOptions {
42
+ /** The widest a video is kept, px: a wider one is scaled down (its own width). */
43
+ width?: number;
44
+ /** The phone file's width, px (720); `false` for none. A video no wider than this gets none. */
45
+ mobile?: number | false;
46
+ /** x264's quality: lower is better and larger, 18 to 28 (23). */
47
+ crf?: number;
48
+ /** A poster for a `<video>` that names none: its first frame (true). */
49
+ poster?: boolean;
50
+ }
51
+
52
+ /** A picture named with a quality floor of its own (`pictures`): a file inside the site's folder, and the floor in dB (the `quality` option, for this file). */
53
+ export interface PictureFile {
54
+ file: string;
55
+ quality: number;
56
+ }
57
+
27
58
  /** What prepareSite() is given. */
28
59
  export interface SiteOptions extends PrepareOptions {
29
60
  /** The built site's folder. */
@@ -35,9 +66,46 @@ export interface SiteOptions extends PrepareOptions {
35
66
  /** Every picture file in `dir`, not only the ones a page has Umber draw. */
36
67
  all?: boolean;
37
68
  /**
38
- * Prepare the fonts of the site's GL text (`data-umber="text"`), so its letters are painted
39
- * from their outlines, sharp at any scale (false: at rest the glyph atlas is closer to the
40
- * browser's own text).
69
+ * More pictures to prepare whether or not a page in the folder shows them: files or folders
70
+ * inside `dir` (`["uploads", "img/work"]`). For pages a server renders, which the tool cannot
71
+ * read (pageWriter() points such a page at them), and for a picture a shader or an effect reads
72
+ * as a uniform: only a picture named here is drawn from its GPU-ready file there, and every
73
+ * page with an element GL draws is pointed at the manifest. A picture that holds data (a depth
74
+ * or normal map, a mask) shows block compression where a photo does not: leave it out.
75
+ * `{ file: "img/detail.jpg", quality: 46 }` names a file with a quality floor of its own.
76
+ */
77
+ pictures?: (string | PictureFile)[];
78
+ /**
79
+ * The site's own number files to pack (height maps, geometry: any typed array saved as bytes),
80
+ * each a path inside `dir` and what it holds: `[{ file: "alps/height.bin", type: "u16" }]`.
81
+ * Whole numbers are stored as differences and every file is deflated, without loss, under a
82
+ * name that is its content's hash. A script loads one with `data()` of
83
+ * `@occluze/umber/prepared`. With any, every page of the folder is pointed at the manifest.
84
+ */
85
+ data?: DataFile[];
86
+ /**
87
+ * A scrubbed video (`data-umber-scrub`) whose index is at the end of its file gets it moved in
88
+ * front of its frames, so it scrubs while it downloads and not only once it is whole (true).
89
+ * No frame changes and nothing is encoded. false: the site's videos stay as they are.
90
+ */
91
+ videos?: boolean;
92
+ /**
93
+ * Encode the site's scrubbed videos with the ffmpeg on this computer: one whose frames are not
94
+ * all keyframes is encoded again so they are (scrubbing backwards then costs what forwards
95
+ * does), each gets a smaller file for phones (`data-umber-scrub-src-mobile`), and each `<video>`
96
+ * without a `poster` gets its first frame as one. Off unless asked for. The tool ships no
97
+ * encoder and downloads none: it runs `ffmpeg` from the PATH (or `$FFMPEG`, or the `ffmpeg`
98
+ * option); with none, the videos stay as they are and `skipped` says so. `true`, or how to encode.
99
+ */
100
+ encodeVideos?: boolean | EncodeOptions;
101
+ /** The ffmpeg `encodeVideos` runs (`$FFMPEG`, else the one on the PATH). */
102
+ ffmpeg?: string;
103
+ /**
104
+ * The fonts of the site's GL text (`data-umber="text"`) are prepared, so its letters are
105
+ * painted from their outlines, sharp at any scale (true). `false`: no font is prepared and GL
106
+ * text is painted from the glyph atlas, the browser's own rasterising of each word. Each
107
+ * prepared font's outlines are a file anyone can download from the site: its licence must
108
+ * allow a converted copy (the tool says so once).
41
109
  */
42
110
  fonts?: boolean;
43
111
  /**
@@ -54,6 +122,21 @@ export interface SiteOptions extends PrepareOptions {
54
122
  tinySize?: number;
55
123
  /** domImages "tiny": the placeholder's AVIF quality, 1 to 100 (50). */
56
124
  tinyQuality?: number;
125
+ /**
126
+ * More of Umber's chunks for every page with a GL element to fetch early, by name ("layers",
127
+ * "warm"...). The tool already names what a page's elements and stylesheets ask for; this is
128
+ * for what only a script does.
129
+ */
130
+ hints?: string[];
131
+ /**
132
+ * The site's effects by name, the same objects it hands to `umber.effect(name, definition)`.
133
+ * A page whose elements name one (`data-umber-effect`) is hinted for the chunks that effect
134
+ * needs, read from its GLSL and options by the engine's own tests. The Vite plugin and the
135
+ * Astro integration read the effects from the site's modules themselves; give them here
136
+ * for `umber assets`, or for an effect the build says it could not read.
137
+ * @example effects: { ripple: { fragment: { color: "color.rgb += snoise(vUv * 4.0);" } } }
138
+ */
139
+ effects?: Record<string, EffectSource>;
57
140
  /** Where prepared files are kept between builds, so an unchanged picture is not made again; false for none ("node_modules/.cache/umber-assets"). */
58
141
  cache?: string | false;
59
142
  /** Where progress goes, one line each (nowhere by default). */
@@ -72,6 +155,14 @@ export interface SiteResult {
72
155
  pages: number;
73
156
  /** Fonts prepared for GL text painted from their outlines. */
74
157
  fonts: number;
158
+ /** Number files packed (`data`). */
159
+ data: number;
160
+ /** Scrubbed videos whose index was moved in front of their frames. */
161
+ videos: number;
162
+ /** Files `encodeVideos` made: videos encoded again, phone files and posters. */
163
+ encoded: number;
164
+ /** Pages that got early hints for Umber's own files (`<link ... data-umber-hint>` in `<head>`). */
165
+ hinted: number;
75
166
  /** Pictures a page names that are not in the folder (another site's, or missing), and pictures that failed, with why. */
76
167
  skipped: string[];
77
168
  /** Bytes written per kind ("bc7", "astc", "etc2", "avif"), and of the source pictures ("source"). */
@@ -85,3 +176,17 @@ export interface SiteResult {
85
176
  * page that shows one. The HTML stays as it was otherwise.
86
177
  */
87
178
  export function prepareSite(options: SiteOptions): Promise<SiteResult>;
179
+
180
+ /** Where pageWriter() finds a prepared site: the `dir`, `baseUrl` and `folder` prepareSite() was given. */
181
+ export type PageWriterOptions = Pick<SiteOptions, "dir" | "baseUrl" | "folder">;
182
+
183
+ /**
184
+ * For a page a server renders, which prepareSite() cannot find in the folder: the same changes,
185
+ * made to HTML you hand it. Call it once when the server starts (it reads what the last run of
186
+ * the tool left in `<dir>/_umber/pages.json`), then the function it gives once per page, with
187
+ * the page's HTML and its own path on the site (`"/work/one"`). The page comes back with the
188
+ * manifest's meta tag, each `<img>` Umber draws at its placeholder or AVIF, the fallback script
189
+ * and the early hints for Umber's own files. A page it wrote before comes back unchanged.
190
+ * Without a run of the tool to read, a page gets its hints only.
191
+ */
192
+ export function pageWriter(options: PageWriterOptions): Promise<(html: string, url: string) => Promise<string>>;
package/types/astro.d.ts CHANGED
@@ -1,21 +1,16 @@
1
1
  /**
2
- * @occluze/umber/astro. In a page's <script>: umber.scroll across Astro's view transitions
3
- * (<ClientRouter />). In astro.config.mjs: the integration that prepares the site's pictures.
4
- *
5
- * <script> import { astroScroll } from "@occluze/umber/astro"; astroScroll(); </script>
6
- *
7
- * The integration prepares the pictures Umber draws once `astro build` has written
8
- * the site (see `@occluze/umber/assets`), Astro's own `<Image />` and `<Picture />` files
9
- * among them. `astro dev` is left alone. While Astro bundles, it minifies the site's own
10
- * shaders and puts Umber's chunks in the site (`<assets>/umber@<version>/chunks/`), so a built
11
- * site loads them from its own origin and passes `script-src 'self'`.
2
+ * @occluze/umber/astro: the Astro integration, for astro.config.mjs. It prepares the pictures
3
+ * Umber draws once `astro build` has written the site (see `@occluze/umber/assets`), Astro's own
4
+ * `<Image />` and `<Picture />` files among them. In `astro dev` the dev server serves Umber's chunks from the installed package. While Astro bundles,
5
+ * it minifies the site's own shaders and puts Umber's chunks in the site
6
+ * (`<assets>/umber-<version>/chunks/`), so a built site loads them from its own origin and passes
7
+ * `script-src 'self'`.
12
8
  *
13
9
  * import umberAstro from "@occluze/umber/astro";
14
10
  * export default defineConfig({ integrations: [umberAstro()] });
15
11
  */
16
12
 
17
- import type { ScrollApi } from "./scroll.js";
18
- import type { SiteOptions } from "./assets";
13
+ import type { SiteOptions } from "./assets.js";
19
14
 
20
15
  /**
21
16
  * prepareSite()'s options (the folder and base URL come from Astro's config), whether to minify the
@@ -24,20 +19,22 @@ import type { SiteOptions } from "./assets";
24
19
  */
25
20
  export type UmberAstroOptions = Omit<SiteOptions, "dir" | "baseUrl" | "log"> & { shaders?: boolean; chunks?: boolean };
26
21
 
27
- /** An Astro integration. */
22
+ /**
23
+ * A hook as Astro calls it. Its options are Astro's own, typed there: naming them here would
24
+ * need `astro` installed to read this file, and a narrower shape of our own is not assignable
25
+ * to Astro's (`astro check` then refuses `integrations: [umberAstro()]`).
26
+ */
27
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the one type every version of Astro's hook options is assignable to
28
+ type AstroHook = (options: any) => void | Promise<void>;
29
+
30
+ /** The integration, assignable to Astro's `AstroIntegration`. */
28
31
  export interface UmberAstroIntegration {
29
- name: "@occluze/umber";
32
+ name: string;
30
33
  hooks: {
31
- "astro:config:setup": (options: { updateConfig: (config: { vite: { plugins: unknown[] } }) => void }) => void;
32
- "astro:config:done": (options: { config: { base: string } }) => void;
33
- "astro:build:done": (options: {
34
- dir: URL;
35
- logger: { info(message: string): void; warn(message: string): void };
36
- }) => Promise<void>;
34
+ "astro:config:setup": AstroHook;
35
+ "astro:config:done": AstroHook;
36
+ "astro:build:done": AstroHook;
37
37
  };
38
38
  }
39
39
 
40
40
  export default function umberAstro(options?: UmberAstroOptions): UmberAstroIntegration;
41
-
42
- /** Holds the page before each swap and measures the new one after it; returns the remover. The engine: the one on the page, or `gl`. */
43
- export declare function astroScroll(gl?: { readonly scroll?: ScrollApi } | null): () => void;
package/types/debug.d.ts CHANGED
@@ -20,7 +20,7 @@ export declare const Debug: UmberModule;
20
20
 
21
21
  /**
22
22
  * The same without umber.use(): mounts the parts for `engine` and returns destroy().
23
- * @example const stop = debug(gl, { outlines: true }); stop();
23
+ * @example const stop = debug(umber, { outlines: true }); stop();
24
24
  */
25
25
  export declare function debug(engine: Umber, options?: DebugOptions): () => void;
26
26
 
package/types/esm.d.ts CHANGED
@@ -5,7 +5,7 @@
5
5
  * src/esm.ts). Every type comes from umber.d.ts (the same API as window.Umber).
6
6
  *
7
7
  * import { createUmber } from "@occluze/umber";
8
- * import type { GL, UmberOptions, EffectDef } from "@occluze/umber";
8
+ * import type { Umber, UmberOptions, EffectDef } from "@occluze/umber";
9
9
  */
10
10
 
11
11
  import type { Umber, UmberOptions, UmberMath } from "./umber.js";
@@ -16,11 +16,7 @@ export declare const version: string;
16
16
  /** Start the engine (once per page; a second call returns the first engine). On the server it does nothing. */
17
17
  export declare function createUmber(options?: UmberOptions): Umber;
18
18
 
19
- /** DOM <-> three.js maths (pure functions, no engine needed). */
20
- export declare const pxPerWorld: UmberMath["pxPerWorld"];
21
- export declare const fitCamera: UmberMath["fitCamera"];
22
- export declare const rectToWorld: UmberMath["rectToWorld"];
23
- export declare const worldToRect: UmberMath["worldToRect"];
19
+ /** The maths as named exports (pure functions, no engine needed). */
24
20
  export declare const damp: UmberMath["damp"];
25
21
  export declare const clamp: UmberMath["clamp"];
26
22
  export declare const lerp: UmberMath["lerp"];
package/types/input.d.ts CHANGED
@@ -3,7 +3,7 @@
3
3
  *
4
4
  * Inputs as Signals: the speed of any Signal, a drag, the pointer's trail, presses and
5
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:
6
+ * element rects, an image's colour. Load the module, then use them from the engine:
7
7
  *
8
8
  * import { Input } from "@occluze/umber/input";
9
9
  * umber.use(Input); // or createUmber({ modules: [Input] })
@@ -178,7 +178,7 @@ export interface ImageColor {
178
178
  readonly ready: Promise<boolean>;
179
179
  }
180
180
 
181
- /** What umber.use(Input) adds to gl. */
181
+ /** What umber.use(Input) adds to the engine. */
182
182
  export interface InputMethods {
183
183
  /**
184
184
  * A <canvas>, ImageBitmap, <video>, <img>, ImageData or { data, width, height } as a
@@ -227,7 +227,7 @@ export interface InputMethods {
227
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
228
  // a umber.scope() carries the methods (s.drag...), and what they make is the scope's.
229
229
  declare module "./umber.js" {
230
- // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- module augmentation: merges InputMethods into GL
230
+ // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- module augmentation: merges InputMethods into Umber
231
231
  interface Umber extends InputMethods {}
232
232
  // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- module augmentation: merges the methods into Scope
233
233
  interface Scope extends Omit<InputMethods, "press"> {}
package/types/loop.d.ts CHANGED
@@ -1,22 +1,17 @@
1
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.
2
+ * Umber's clock as a site sees it (re-exported by umber.d.ts): umber.on("frame") and umber.on("step") options and
3
+ * umber.loop (pause, play, restart, fps, the profiler).
4
4
  */
5
5
 
6
6
  import type { TickPhase } from "./umber.js";
7
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
8
  /** How a umber.on("frame") callback runs. */
14
9
  export interface FrameOptions {
15
10
  /** @default "update" */
16
11
  phase?: TickPhase;
17
12
  /** Lower runs first inside its phase. @default 0 */
18
13
  order?: number;
19
- /** false: only ride along on frames Umber runs anyway. @default true */
14
+ /** false: only ride along on frames Umber runs anyway (for umber.on("step"): frames the loop runs anyway). @default true */
20
15
  always?: boolean;
21
16
  /**
22
17
  * Its own rate: at most this many runs a second (30), or a share of the frames the loop
@@ -26,8 +21,24 @@ export interface FrameOptions {
26
21
  fps?: number | `${number}%`;
27
22
  /** Its name in the profiler (umber.loop.profile()). */
28
23
  label?: string;
24
+ /**
25
+ * Run only while this element (or the first one a selector finds) is on the screen or
26
+ * within a quarter of a screen of it: off the loop the rest of the time, so it keeps no
27
+ * frame running for something nobody sees. A selector is looked up once, when the callback
28
+ * is added; one that finds nothing runs as if no `el` was given.
29
+ * @example umber.on("frame", spin, { el: ".hero" })
30
+ */
31
+ el?: Element | string;
29
32
  }
30
33
 
34
+ /**
35
+ * How a umber.on("step") callback runs. It runs first in the frame, before Umber reads the
36
+ * page: step a scroller of your own there. It keeps the loop running like a "frame" callback,
37
+ * but not Umber's own part of the frame, which runs only when the page moved or something
38
+ * else changed.
39
+ */
40
+ export type StepOptions = Omit<FrameOptions, "phase">;
41
+
31
42
  /** umber.loop: Umber's clock as a whole (with createUmber({ patch: true }), the page's loops too). */
32
43
  export interface Loop {
33
44
  /** Stop every frame callback (and the patched loops) until play(). Unlike umber.pause(), GL keeps its planes on screen as they are. */
@@ -59,7 +70,8 @@ export interface ProfilerOptions {
59
70
  /** One frame callback (or patched page loop) as the profiler measured it. */
60
71
  export interface ProfileLine {
61
72
  label: string;
62
- phase: TickPhase;
73
+ /** "step": before Umber's own part (a umber.on("step") callback, a patched page loop). */
74
+ phase: TickPhase | "step";
63
75
  order: number;
64
76
  /** "30 fps", "50%", "page" (one of the page's own loops, patched in), or "". */
65
77
  rate: string;
package/types/module.d.ts CHANGED
@@ -37,8 +37,6 @@ export interface PlaneModuleContext {
37
37
  maxTexture: number;
38
38
  isTouch: boolean;
39
39
  readonly reducedMotion: boolean;
40
- /** What the engine reads scroll from. */
41
- scrollKind: "window" | "element" | "lenis" | "object";
42
40
  /** The engine's console: warnings and errors as the engine's own (shown once each), info with debug on. */
43
41
  log: ModuleLog & { info(...args: unknown[]): void };
44
42
  /** Draw every frame while on (smoothing towards a target). */