@occluze/umber 0.3.0 → 0.4.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.
- package/README.md +93 -47
- package/THIRD-PARTY-NOTICES.md +33 -0
- package/dist/chunks/badge.js +2 -2
- package/dist/chunks/basis.js +2 -2
- package/dist/chunks/batches.js +2 -0
- package/dist/chunks/capture.js +2 -2
- package/dist/chunks/covers.js +2 -2
- package/dist/chunks/curves.js +2 -2
- package/dist/chunks/flip.js +2 -2
- package/dist/chunks/fx.js +2 -2
- package/dist/chunks/gl.js +2 -2
- package/dist/chunks/glsl.js +2 -2
- package/dist/chunks/glyphs.js +2 -0
- package/dist/chunks/inspect.js +2 -2
- package/dist/chunks/instances.js +2 -2
- package/dist/chunks/layers.js +2 -2
- package/dist/chunks/licence.js +2 -2
- package/dist/chunks/morph.js +2 -2
- package/dist/chunks/pace.js +2 -0
- package/dist/chunks/patch.js +2 -2
- package/dist/chunks/prepared.js +2 -2
- package/dist/chunks/profiler.js +2 -2
- package/dist/chunks/recheck.js +2 -0
- package/dist/chunks/resize.js +2 -0
- package/dist/chunks/restore.js +2 -2
- package/dist/chunks/shapes.js +2 -2
- package/dist/chunks/sim.js +2 -2
- package/dist/chunks/text.js +2 -2
- package/dist/chunks/video.js +2 -2
- package/dist/chunks/vocabulary.js +2 -2
- package/dist/chunks/warm.js +2 -2
- package/dist/modules/debug.js +2 -2
- package/dist/modules/debug.mjs +2 -2
- package/dist/modules/handoff.js +2 -2
- package/dist/modules/handoff.mjs +2 -2
- package/dist/modules/input.js +2 -2
- package/dist/modules/input.mjs +2 -2
- package/dist/modules/scrollfx.js +2 -2
- package/dist/modules/scrollfx.mjs +2 -2
- package/dist/modules/scrub.js +2 -2
- package/dist/modules/scrub.mjs +2 -2
- package/dist/modules/three.js +2 -2
- package/dist/modules/three.mjs +2 -2
- package/dist/node/assets.mjs +4 -2
- package/dist/node/astro.mjs +26 -18
- package/dist/node/cli.mjs +63 -10
- package/dist/node/shared-P6KINBNR.mjs +2113 -0
- package/dist/node/{shared-4FIU6DYP.mjs → shared-VQKZUUXF.mjs} +106 -17
- package/dist/node/vite.mjs +7 -3
- package/dist/prepared.mjs +2 -0
- package/dist/umber.css +1 -1
- package/dist/umber.js +2 -2
- package/dist/umber.mjs +2 -2
- package/docs/AI-quick.md +43 -87
- package/docs/AI.md +1965 -1828
- package/docs/npm.md +13 -16
- package/package.json +31 -48
- package/types/assets.d.ts +109 -4
- package/types/astro.d.ts +20 -23
- package/types/debug.d.ts +1 -1
- package/types/esm.d.ts +2 -6
- package/types/input.d.ts +3 -3
- package/types/loop.d.ts +21 -9
- package/types/module.d.ts +0 -2
- package/types/scrollfx.d.ts +5 -41
- package/types/scrub.d.ts +2 -2
- package/types/three.d.ts +26 -1
- package/types/umber.d.ts +152 -155
- package/types/vite.d.ts +3 -3
- package/dist/chunks/views.js +0 -2
- package/dist/frameworks/astro.mjs +0 -2
- package/dist/frameworks/react.mjs +0 -2
- package/dist/frameworks/svelte.mjs +0 -2
- package/dist/frameworks/vue.mjs +0 -2
- package/dist/modules/router-swap.js +0 -2
- package/dist/modules/router.js +0 -2
- package/dist/modules/router.mjs +0 -2
- package/dist/modules/scroll-more.js +0 -2
- package/dist/modules/scroll-touch.js +0 -2
- package/dist/modules/scroll.js +0 -2
- package/dist/modules/scroll.mjs +0 -2
- package/dist/node/shared-3Q24RNIF.mjs +0 -602
- package/types/react.d.ts +0 -15
- package/types/router.d.ts +0 -223
- package/types/scroll.d.ts +0 -190
- package/types/svelte.d.ts +0 -16
- 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
|
|
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" })
|
|
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.
|
|
19
|
+
// npm install --save-exact @occluze/umber@0.4.0
|
|
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"
|
|
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
|
|
32
|
-
import
|
|
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
|
|
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: `
|
|
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`)
|
|
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
|
|
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
|
+
"version": "0.4.0",
|
|
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
|
-
"
|
|
75
|
-
"
|
|
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",
|
|
@@ -246,13 +224,11 @@
|
|
|
246
224
|
"entry": [
|
|
247
225
|
"src/umber.ts",
|
|
248
226
|
"src/esm.ts",
|
|
227
|
+
"src/prepared.ts",
|
|
249
228
|
"src/umber.css",
|
|
250
229
|
"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",
|
|
230
|
+
"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
231
|
"src/modules/*/{index,from-script}.ts",
|
|
254
|
-
"src/frameworks/{react,vue,svelte,astro}.ts",
|
|
255
|
-
"src/modules/router/swap.ts",
|
|
256
232
|
"types/*.d.ts",
|
|
257
233
|
"scripts/*.mjs",
|
|
258
234
|
"deploy/*.mjs",
|
|
@@ -260,9 +236,16 @@
|
|
|
260
236
|
"test/browser/*.mjs",
|
|
261
237
|
"test/browser/fixtures/*.js",
|
|
262
238
|
"test/browser/clock/*.js",
|
|
239
|
+
"test/browser/scrollers/*.js",
|
|
240
|
+
"test/browser/routers/*.js",
|
|
263
241
|
"test/browser/csp/*.js",
|
|
264
242
|
"test/browser/csp/site/*.js",
|
|
265
243
|
"test/browser/bench/*.js",
|
|
244
|
+
"test/browser/heavy/*.mjs",
|
|
245
|
+
"test/browser/heavy/lib/effects.mjs",
|
|
246
|
+
"test/browser/heavy/site/*.js",
|
|
247
|
+
"test/browser/rivals/*/*.{mjs,js}",
|
|
248
|
+
"test/browser/rivals/*/site/*.js",
|
|
266
249
|
"test/dist/*.ts",
|
|
267
250
|
"tools/assets/{cli,index,vite,astro}.ts"
|
|
268
251
|
],
|
|
@@ -281,11 +264,11 @@
|
|
|
281
264
|
]
|
|
282
265
|
},
|
|
283
266
|
"optionalDependencies": {
|
|
284
|
-
"@occluze/umber-assets-win32-x64-msvc": "0.
|
|
285
|
-
"@occluze/umber-assets-win32-arm64-msvc": "0.
|
|
286
|
-
"@occluze/umber-assets-darwin-x64": "0.
|
|
287
|
-
"@occluze/umber-assets-darwin-arm64": "0.
|
|
288
|
-
"@occluze/umber-assets-linux-x64-gnu": "0.
|
|
289
|
-
"@occluze/umber-assets-linux-arm64-gnu": "0.
|
|
267
|
+
"@occluze/umber-assets-win32-x64-msvc": "0.4.0",
|
|
268
|
+
"@occluze/umber-assets-win32-arm64-msvc": "0.4.0",
|
|
269
|
+
"@occluze/umber-assets-darwin-x64": "0.4.0",
|
|
270
|
+
"@occluze/umber-assets-darwin-arm64": "0.4.0",
|
|
271
|
+
"@occluze/umber-assets-linux-x64-gnu": "0.4.0",
|
|
272
|
+
"@occluze/umber-assets-linux-arm64-gnu": "0.4.0"
|
|
290
273
|
}
|
|
291
274
|
}
|
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
|
-
*
|
|
39
|
-
*
|
|
40
|
-
*
|
|
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
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
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 {
|
|
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
|
-
/**
|
|
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:
|
|
32
|
+
name: string;
|
|
30
33
|
hooks: {
|
|
31
|
-
"astro:config:setup":
|
|
32
|
-
"astro:config:done":
|
|
33
|
-
"astro:build:done":
|
|
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(
|
|
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 {
|
|
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
|
-
/**
|
|
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
|
|
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
|
|
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
|
|
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)
|
|
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
|
-
|
|
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). */
|