@occluze/umber 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/LICENSE.md +21 -0
  2. package/README.md +78 -48
  3. package/dist/chunks/badge.js +2 -0
  4. package/dist/chunks/basis.js +2 -0
  5. package/dist/chunks/basis_transcoder.js +2 -0
  6. package/dist/chunks/basis_transcoder.wasm +0 -0
  7. package/dist/chunks/capture.js +2 -2
  8. package/dist/chunks/covers.js +2 -2
  9. package/dist/chunks/curves.js +2 -0
  10. package/dist/chunks/flip.js +2 -2
  11. package/dist/chunks/fx.js +2 -102
  12. package/dist/chunks/gl.js +2 -180
  13. package/dist/chunks/glsl.js +2 -239
  14. package/dist/chunks/inspect.js +2 -6
  15. package/dist/chunks/instances.js +2 -93
  16. package/dist/chunks/layers.js +2 -21
  17. package/dist/chunks/licence.js +2 -2
  18. package/dist/chunks/morph.js +2 -2
  19. package/dist/chunks/patch.js +2 -0
  20. package/dist/chunks/prepared.js +2 -0
  21. package/dist/chunks/profiler.js +2 -0
  22. package/dist/chunks/restore.js +2 -2
  23. package/dist/chunks/shapes.js +2 -2
  24. package/dist/chunks/sim.js +2 -22
  25. package/dist/chunks/text.js +2 -52
  26. package/dist/chunks/video.js +2 -2
  27. package/dist/chunks/views.js +2 -2
  28. package/dist/chunks/vocabulary.js +2 -0
  29. package/dist/chunks/warm.js +2 -2
  30. package/dist/frameworks/astro.mjs +2 -0
  31. package/dist/frameworks/react.mjs +2 -0
  32. package/dist/frameworks/svelte.mjs +2 -0
  33. package/dist/frameworks/vue.mjs +2 -0
  34. package/dist/modules/debug.js +2 -36
  35. package/dist/modules/debug.mjs +2 -36
  36. package/dist/modules/handoff.js +2 -2
  37. package/dist/modules/handoff.mjs +2 -2
  38. package/dist/modules/input.js +2 -2
  39. package/dist/modules/input.mjs +2 -2
  40. package/dist/modules/router-swap.js +2 -13
  41. package/dist/modules/router.js +2 -2
  42. package/dist/modules/router.mjs +2 -2
  43. package/dist/modules/scroll-more.js +2 -0
  44. package/dist/modules/scroll-touch.js +2 -0
  45. package/dist/modules/scroll.js +2 -2
  46. package/dist/modules/scroll.mjs +2 -2
  47. package/dist/modules/scrollfx.js +2 -0
  48. package/dist/modules/scrollfx.mjs +2 -0
  49. package/dist/modules/scrub.js +2 -8
  50. package/dist/modules/scrub.mjs +2 -8
  51. package/dist/modules/three.js +2 -0
  52. package/dist/modules/three.mjs +2 -0
  53. package/dist/node/assets.mjs +9 -0
  54. package/dist/node/astro.mjs +47 -0
  55. package/dist/node/cli.mjs +109 -0
  56. package/dist/node/shared-3Q24RNIF.mjs +602 -0
  57. package/dist/node/shared-4FIU6DYP.mjs +200 -0
  58. package/dist/node/vite.mjs +10 -0
  59. package/dist/umber.css +2 -2
  60. package/dist/umber.js +2 -2
  61. package/dist/umber.mjs +2 -2
  62. package/docs/AI-quick.md +116 -54
  63. package/docs/AI.md +1275 -805
  64. package/docs/npm.md +37 -26
  65. package/package.json +181 -12
  66. package/types/assets.d.ts +87 -0
  67. package/types/astro.d.ts +43 -0
  68. package/types/debug.d.ts +17 -16
  69. package/types/esm.d.ts +12 -12
  70. package/types/global.d.ts +17 -0
  71. package/types/handoff.d.ts +26 -25
  72. package/types/input.d.ts +63 -55
  73. package/types/loop.d.ts +75 -0
  74. package/types/module.d.ts +108 -0
  75. package/types/react.d.ts +15 -0
  76. package/types/router.d.ts +87 -45
  77. package/types/scroll.d.ts +96 -38
  78. package/types/scrollfx.d.ts +80 -0
  79. package/types/scrub.d.ts +33 -32
  80. package/types/svelte.d.ts +16 -0
  81. package/types/three.d.ts +226 -0
  82. package/types/umber.d.ts +633 -357
  83. package/types/vite.d.ts +33 -0
  84. package/types/vue.d.ts +14 -0
package/docs/npm.md CHANGED
@@ -7,21 +7,22 @@ For bundled sites (Astro, Vite, Next.js) Umber is also an npm package, `@occluze
7
7
  Install the version you want, exactly:
8
8
 
9
9
  ```bash
10
- npm install @occluze/umber@x.y.z --save-exact
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 the domain list: Umber runs on the domains its developer listed under Umber in their occluze dashboard (and on `localhost` while you build), as [hosting.md](hosting.md) says.
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)).
14
14
 
15
15
  ## Use it
16
16
 
17
17
  <!-- snippet:npm -->
18
18
  ```js
19
- // npm install @occluze/umber@0.2.1 (docs/npm.md)
20
- import { createGL } from "@occluze/umber";
19
+ // npm install @occluze/umber@0.3.0 (docs/npm.md)
20
+ import { createUmber } from "@occluze/umber";
21
21
  import "@occluze/umber/umber.css";
22
- import { Scrub } from "@occluze/umber/scrub"; // optional module
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
23
24
 
24
- const gl = createGL({ modules: [Scrub] }); // client code only; on the server it does nothing
25
+ const umber = createUmber({ key: "YOUR_KEY", modules: [Scroll, Router] }); // client code only; on the server it does nothing
25
26
  ```
26
27
  <!-- /snippet -->
27
28
 
@@ -29,41 +30,51 @@ const gl = createGL({ modules: [Scrub] }); // client code only; on t
29
30
  // src/site.js (runs in the browser). Your libraries stay yours: Umber never imports them.
30
31
  import Lenis from "lenis";
31
32
  import barba from "@barba/core";
32
- import { createGL } from "@occluze/umber";
33
+ import { createUmber } from "@occluze/umber";
33
34
  import { Debug } from "@occluze/umber/debug"; // while you build only
34
35
  import { dissolve } from "./gl/effects.js"; // your own effects
35
36
 
36
37
  const lenis = new Lenis({ autoRaf: true });
37
- const gl = createGL({ scroll: lenis, modules: import.meta.env.DEV ? [Debug] : [] });
38
- gl.effect("dissolve", dissolve);
38
+ const umber = createUmber({ scroll: lenis, modules: import.meta.env.DEV ? [Debug] : [] });
39
+ umber.effect("dissolve", dissolve);
39
40
  barba.init({ /* your transitions */ });
40
41
  ```
41
42
 
42
- - **Exports:** `.` (`createGL`, `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`), `./router` (`Router`, `router`; its second file, `dist/modules/router-swap.js`, is `import()`ed from it, so your bundler splits it off), `./umber.css`, `./umber.js` (the script build, sets `window.Umber`). Types are included for all of them (`import type { GL, GLOptions, EffectDef } from "@occluze/umber"`).
43
- - **Nothing runs on import.** Importing in server-rendered files (Astro frontmatter, a Next.js component) is safe; on the server `createGL()` returns an engine that does nothing (`gl.enabled` false, `gl.reason` `"server"`). Call it from code that runs in the browser (Astro: a `<script>`; Next.js: `useEffect` or a client-only module).
44
- - **One engine per page.** When a `umber.js` `<script>` already started an engine, `createGL()` returns that one (with a warning) instead of starting a second.
45
- - **No effects ship in the package.** You write them with `gl.effect()` ("Writing effects" in [AI.md](AI.md)).
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" />`.
44
+ - **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
+ - **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
+ - **No effects ship in the package.** You write them with `umber.effect()` ("Writing effects" in [AI.md](AI.md)).
46
47
 
47
- ## The GL chunk still comes from the CDN
48
+ ## Where the chunks come from
48
49
 
49
- 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 from the engine's CDN folder, at the exact version of the package:
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.
50
51
 
51
- - default: `https://umber.occluze.com/umber@<version>/`. There is no key: the files are served to anyone, and the licence check (`chunks/licence.js`, next to `chunks/gl.js`) decides whether GL starts on this domain.
52
- - to load them from somewhere else (a staging copy of the engine, say):
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:
53
53
 
54
- ```js
55
- import { createGL } from "@occluze/umber";
56
- createGL({ base: "https://umber.occluze.com/umber@x.y.z/" });
57
- // or, before createGL() runs: window.UmberConfig = { base: "..." }
54
+ ```
55
+ /assets/umber@*
56
+ Cache-Control: public, max-age=31536000, immutable
58
57
  ```
59
58
 
60
- Keep the version in that URL the same as the package version.
59
+ - **Any other bundler:** from the CDN folder of the package's version, `https://umber.occluze.com/umber@<version>/`.
60
+ - **Self-hosting without a plugin:** copy the package's `dist/chunks/` (the `.js` files and `basis_transcoder.wasm`) to a folder your site serves, as `chunks/` inside a folder named for the version, and point the engine at that folder. Copy it again on every update of the package, so the chunks always match it:
61
+
62
+ ```bash
63
+ mkdir -p public/umber@x.y.z
64
+ cp -r node_modules/@occluze/umber/dist/chunks public/umber@x.y.z/
65
+ ```
66
+
67
+ ```js
68
+ import { createUmber } from "@occluze/umber";
69
+ createUmber({ base: "/umber@x.y.z/" });
70
+ // or, before createUmber() runs: window.UmberConfig = { base: "/umber@x.y.z/" }
71
+ ```
61
72
 
62
- Self-hosting instead: copy `node_modules/@occluze/umber/dist/` to your public folder and set `base` to that folder.
73
+ `base` (or `window.UmberConfig.base`) wins over the plugin's folder and the CDN alike.
63
74
 
64
75
  ## Honest limits
65
76
 
66
- - **The code is public once a site uses it**, as with any front-end code: anyone can read the files a page loads. The domain list is what licenses Umber; the files ship minified, without source maps.
67
- - **The chunks come from the CDN**: 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.
68
- - **Mixing versions:** the package version and the `base` URL version must match. A mismatch can load a GL chunk of another version.
77
+ - **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
+ - **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
+ - **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.
69
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,8 +1,8 @@
1
1
  {
2
2
  "name": "@occluze/umber",
3
- "version": "0.2.1",
4
- "description": "Umber: a DOM-to-WebGL engine that works next to Barba, Lenis and GSAP and controls none of them. Tag DOM elements; Umber draws them as GPU planes on one canvas, kept in line with the page.",
5
- "license": "UNLICENSED",
3
+ "version": "0.3.0",
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
+ "license": "SEE LICENSE IN LICENSE.md",
6
6
  "homepage": "https://github.com/ravi-klaassens/umber#readme",
7
7
  "repository": {
8
8
  "type": "git",
@@ -15,6 +15,9 @@
15
15
  "main": "./dist/umber.mjs",
16
16
  "module": "./dist/umber.mjs",
17
17
  "types": "./types/esm.d.ts",
18
+ "bin": {
19
+ "umber": "./dist/node/cli.mjs"
20
+ },
18
21
  "exports": {
19
22
  ".": {
20
23
  "types": "./types/esm.d.ts",
@@ -46,34 +49,99 @@
46
49
  "import": "./dist/modules/scroll.mjs",
47
50
  "default": "./dist/modules/scroll.mjs"
48
51
  },
52
+ "./scrollfx": {
53
+ "types": "./types/scrollfx.d.ts",
54
+ "import": "./dist/modules/scrollfx.mjs",
55
+ "default": "./dist/modules/scrollfx.mjs"
56
+ },
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
+ "./astro": {
73
+ "types": "./types/astro.d.ts",
74
+ "browser": "./dist/frameworks/astro.mjs",
75
+ "node": "./dist/node/astro.mjs",
76
+ "default": "./dist/frameworks/astro.mjs"
77
+ },
78
+ "./module": {
79
+ "types": "./types/module.d.ts"
80
+ },
49
81
  "./router": {
50
82
  "types": "./types/router.d.ts",
51
83
  "import": "./dist/modules/router.mjs",
52
84
  "default": "./dist/modules/router.mjs"
53
85
  },
86
+ "./three": {
87
+ "types": "./types/three.d.ts",
88
+ "import": "./dist/modules/three.mjs",
89
+ "default": "./dist/modules/three.mjs"
90
+ },
54
91
  "./umber.css": "./dist/umber.css",
55
92
  "./umber.js": "./dist/umber.js",
56
- "./types": "./types/umber.d.ts",
93
+ "./types": {
94
+ "types": "./types/umber.d.ts"
95
+ },
96
+ "./global": {
97
+ "types": "./types/global.d.ts"
98
+ },
99
+ "./assets": {
100
+ "types": "./types/assets.d.ts",
101
+ "import": "./dist/node/assets.mjs",
102
+ "default": "./dist/node/assets.mjs"
103
+ },
104
+ "./vite": {
105
+ "types": "./types/vite.d.ts",
106
+ "import": "./dist/node/vite.mjs",
107
+ "default": "./dist/node/vite.mjs"
108
+ },
57
109
  "./package.json": "./package.json"
58
110
  },
59
111
  "files": [
112
+ "LICENSE.md",
60
113
  "dist/umber.mjs",
61
114
  "dist/umber.js",
62
115
  "dist/umber.css",
63
116
  "dist/chunks/*.js",
117
+ "dist/chunks/*.wasm",
64
118
  "dist/modules/*.js",
65
119
  "dist/modules/*.mjs",
120
+ "dist/frameworks/*.mjs",
121
+ "dist/node/*.mjs",
66
122
  "types/umber.d.ts",
123
+ "types/global.d.ts",
67
124
  "types/esm.d.ts",
68
125
  "types/scrub.d.ts",
69
126
  "types/debug.d.ts",
70
127
  "types/input.d.ts",
71
128
  "types/handoff.d.ts",
72
129
  "types/scroll.d.ts",
130
+ "types/scrollfx.d.ts",
131
+ "types/react.d.ts",
132
+ "types/vue.d.ts",
133
+ "types/svelte.d.ts",
134
+ "types/astro.d.ts",
73
135
  "types/router.d.ts",
136
+ "types/three.d.ts",
137
+ "types/module.d.ts",
138
+ "types/loop.d.ts",
74
139
  "docs/npm.md",
75
140
  "docs/AI.md",
76
- "docs/AI-quick.md"
141
+ "docs/AI-quick.md",
142
+ "types/assets.d.ts",
143
+ "types/vite.d.ts",
144
+ "types/astro.d.ts"
77
145
  ],
78
146
  "sideEffects": [
79
147
  "*.css",
@@ -83,18 +151,34 @@
83
151
  "./dist/modules/input.js",
84
152
  "./dist/modules/handoff.js",
85
153
  "./dist/modules/scroll.js",
86
- "./dist/modules/router.js"
154
+ "./dist/modules/scrollfx.js",
155
+ "./dist/modules/router.js",
156
+ "./dist/modules/three.js"
87
157
  ],
88
158
  "publishConfig": {
89
159
  "registry": "https://registry.npmjs.org",
90
160
  "access": "public"
91
161
  },
162
+ "peerDependencies": {
163
+ "three": ">=0.160.0"
164
+ },
165
+ "peerDependenciesMeta": {
166
+ "three": {
167
+ "optional": true
168
+ }
169
+ },
92
170
  "scripts": {
93
171
  "build": "node scripts/build.mjs && node scripts/docs.mjs",
94
172
  "dev": "node scripts/build.mjs --watch --serve",
95
- "typecheck": "tsc --noEmit",
96
- "test": "vitest run",
173
+ "typecheck": "tsc -b",
174
+ "test": "vitest run --config .config/vitest.config.mjs --project unit --coverage && vitest run --config .config/vitest.config.mjs --project dist",
175
+ "lint": "eslint .",
176
+ "format:check": "prettier --check .",
177
+ "knip": "knip",
178
+ "deps": "depcruise src --config .config/dependency-cruiser.cjs",
179
+ "check": "npm run typecheck && npm run lint && npm run format:check && npm test && npm run knip && npm run deps",
97
180
  "check:browser": "node test/browser/all.mjs",
181
+ "check:browser:changed": "node test/browser/changed.mjs",
98
182
  "check:oracle": "node test/browser/oracle.mjs",
99
183
  "check:render": "node test/browser/render.mjs",
100
184
  "check:idle": "node test/browser/idle.mjs",
@@ -104,19 +188,104 @@
104
188
  "check:stress": "node test/browser/stress.mjs",
105
189
  "check:capture": "node test/browser/capture.mjs",
106
190
  "check:router": "node test/browser/router.mjs",
191
+ "check:modules": "node test/browser/modules.mjs",
192
+ "check:fade": "node test/browser/fade.mjs",
193
+ "check:clock": "node test/browser/clock.mjs",
194
+ "check:three": "node test/browser/three.mjs",
195
+ "check:pictures": "node test/browser/pictures.mjs",
196
+ "check:licence": "node test/browser/licence.mjs",
197
+ "check:csp": "node test/browser/csp.mjs",
198
+ "check:curves": "node test/browser/curves.mjs",
199
+ "check:tiny": "node test/browser/tiny.mjs",
107
200
  "scrub": "node scripts/scrub.mjs",
108
201
  "release": "node deploy/release.mjs",
109
- "deploy": "cd deploy && wrangler pages deploy site --project-name umber --branch main",
110
- "prepublishOnly": "npm run build"
202
+ "deploy": "node deploy/deploy.mjs",
203
+ "deploy:staging": "node deploy/deploy.mjs --staging",
204
+ "prepublishOnly": "npm run build",
205
+ "prepare": "simple-git-hooks",
206
+ "build:native": "node scripts/native.mjs",
207
+ "test:native": "cargo test --manifest-path crates/Cargo.toml"
111
208
  },
112
209
  "devDependencies": {
210
+ "@eslint/js": "10.0.1",
211
+ "@types/node": "22.20.5",
212
+ "@types/three": "0.178.1",
213
+ "@vitest/coverage-v8": "4.1.12",
214
+ "acorn": "8.19.0",
215
+ "dependency-cruiser": "18.7.2",
113
216
  "esbuild": "0.25.10",
114
- "happy-dom": "18.0.1",
217
+ "eslint": "10.14.0",
218
+ "eslint-plugin-sonarjs": "4.2.2",
219
+ "globals": "17.14.0",
220
+ "happy-dom": "21.0.4",
221
+ "knip": "6.44.1",
115
222
  "lenis": "1.3.23",
116
223
  "pixelmatch": "7.2.0",
117
224
  "playwright": "1.63.0",
225
+ "prettier": "3.9.10",
226
+ "simple-git-hooks": "2.14.0",
227
+ "tempus": "1.0.0",
228
+ "terser": "5.51.2",
229
+ "three": "0.178.0",
118
230
  "typescript": "5.9.3",
119
- "vitest": "3.2.4",
231
+ "typescript-eslint": "8.72.1",
232
+ "vitest": "4.1.12",
120
233
  "wrangler": "4.156.2"
234
+ },
235
+ "simple-git-hooks": {
236
+ "pre-commit": "npm run check",
237
+ "commit-msg": "node scripts/commit-msg.mjs \"$1\""
238
+ },
239
+ "overrides": {
240
+ "minimatch": "11.0.5"
241
+ },
242
+ "prettier": {
243
+ "printWidth": 120
244
+ },
245
+ "knip": {
246
+ "entry": [
247
+ "src/umber.ts",
248
+ "src/esm.ts",
249
+ "src/umber.css",
250
+ "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",
253
+ "src/modules/*/{index,from-script}.ts",
254
+ "src/frameworks/{react,vue,svelte,astro}.ts",
255
+ "src/modules/router/swap.ts",
256
+ "types/*.d.ts",
257
+ "scripts/*.mjs",
258
+ "deploy/*.mjs",
259
+ "deploy/functions/**/*.js",
260
+ "test/browser/*.mjs",
261
+ "test/browser/fixtures/*.js",
262
+ "test/browser/clock/*.js",
263
+ "test/browser/csp/*.js",
264
+ "test/browser/csp/site/*.js",
265
+ "test/browser/bench/*.js",
266
+ "test/dist/*.ts",
267
+ "tools/assets/{cli,index,vite,astro}.ts"
268
+ ],
269
+ "project": [
270
+ "src/**/*.ts",
271
+ "types/**/*.ts",
272
+ "scripts/**/*.{mjs,mts}",
273
+ "deploy/**/*.{mjs,js}",
274
+ "test/**/*.{ts,mjs,js}",
275
+ "tools/**/*.ts"
276
+ ],
277
+ "ignoreDependencies": [
278
+ "lenis",
279
+ "tempus",
280
+ "wrangler"
281
+ ]
282
+ },
283
+ "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"
121
290
  }
122
291
  }
@@ -0,0 +1,87 @@
1
+ /**
2
+ * `@occluze/umber/assets`: Umber's build-time asset tool, from a script of your own. It runs in
3
+ * Node at your site's build, never in a visitor's browser. The `umber assets` command, the Vite
4
+ * plugin (`@occluze/umber/vite`) and the Astro integration (`@occluze/umber/astro`) call the same.
5
+ */
6
+
7
+ /** How pictures are prepared. Every field may be left out. */
8
+ export interface PrepareOptions {
9
+ /** The GPU formats to make: "bc7" (desktops, Macs included), "astc" (phones, tablets), "etc2" (Android). All three by default. */
10
+ formats?: ("bc7" | "astc" | "etc2")[];
11
+ /** Make an AVIF for a GPU with none of those formats (true). */
12
+ avif?: boolean;
13
+ /** The AVIF's quality, 1 to 100 (80). */
14
+ avifQuality?: number;
15
+ /** How hard the encoders try: "fast", "normal" (the default) or "best" (slowest, closest to the source). */
16
+ effort?: "fast" | "normal" | "best";
17
+ /** The longest side of the largest level, px (4096): a bigger picture is scaled down to it. */
18
+ maxSize?: number;
19
+ /**
20
+ * The quality floor, dB (40): each GPU file is the smallest (format, ASTC block size,
21
+ * rate-distortion optimisation) whose largest level stays at least this close to the
22
+ * picture (PSNR of its colours).
23
+ */
24
+ quality?: number;
25
+ }
26
+
27
+ /** What prepareSite() is given. */
28
+ export interface SiteOptions extends PrepareOptions {
29
+ /** The built site's folder. */
30
+ dir: string;
31
+ /** The URL path the folder is served at ("/", or the site's base, "/docs/"). */
32
+ baseUrl?: string;
33
+ /** The folder inside `dir` the prepared files go to ("_umber"). */
34
+ folder?: string;
35
+ /** Every picture file in `dir`, not only the ones a page has Umber draw. */
36
+ all?: boolean;
37
+ /**
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).
41
+ */
42
+ fonts?: boolean;
43
+ /**
44
+ * What the page's own <img> of a prepared picture shows. "tiny" (the default): a small
45
+ * placeholder AVIF while GL loads, so a visitor whose GPU draws the picture downloads that
46
+ * and the GPU file only; wherever GL won't draw it (no WebGL2, GL off, printing, Umber's
47
+ * script not running 3 s after the page loaded) the <img> loads the full AVIF in its place, at
48
+ * the same size. "avif": the picture's AVIF when that is smaller, so the page downloads it
49
+ * and the GPU file instead of the full file too. "source": the file as it was. The <img>'s
50
+ * own src never changes, so search engines index the original picture.
51
+ */
52
+ domImages?: "tiny" | "avif" | "source";
53
+ /** domImages "tiny": the placeholder's longer side, px, a whole number from 16 to 4096 (512). */
54
+ tinySize?: number;
55
+ /** domImages "tiny": the placeholder's AVIF quality, 1 to 100 (50). */
56
+ tinyQuality?: number;
57
+ /** Where prepared files are kept between builds, so an unchanged picture is not made again; false for none ("node_modules/.cache/umber-assets"). */
58
+ cache?: string | false;
59
+ /** Where progress goes, one line each (nowhere by default). */
60
+ log?: (line: string) => void;
61
+ }
62
+
63
+ /** What prepareSite() did. */
64
+ export interface SiteResult {
65
+ /** The manifest's URL (what each page's `<meta name="umber-assets">` points at), or null when no page has a picture Umber draws. */
66
+ manifest: string | null;
67
+ /** Pictures prepared now. */
68
+ prepared: number;
69
+ /** Pictures taken from the cache. */
70
+ cached: number;
71
+ /** Pages that got the meta tag. */
72
+ pages: number;
73
+ /** Fonts prepared for GL text painted from their outlines. */
74
+ fonts: number;
75
+ /** Pictures a page names that are not in the folder (another site's, or missing), and pictures that failed, with why. */
76
+ skipped: string[];
77
+ /** Bytes written per kind ("bc7", "astc", "etc2", "avif"), and of the source pictures ("source"). */
78
+ bytes: Record<string, number>;
79
+ }
80
+
81
+ /**
82
+ * Prepare the pictures Umber draws on a built site (the `<img>`, `srcset` and `data-umber-src`
83
+ * inside `[data-umber]` elements): BC7, ASTC and ETC2 textures with all their mip levels and an
84
+ * AVIF in `<dir>/_umber/`, a manifest next to them, and `<meta name="umber-assets">` on every
85
+ * page that shows one. The HTML stays as it was otherwise.
86
+ */
87
+ export function prepareSite(options: SiteOptions): Promise<SiteResult>;
@@ -0,0 +1,43 @@
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'`.
12
+ *
13
+ * import umberAstro from "@occluze/umber/astro";
14
+ * export default defineConfig({ integrations: [umberAstro()] });
15
+ */
16
+
17
+ import type { ScrollApi } from "./scroll.js";
18
+ import type { SiteOptions } from "./assets";
19
+
20
+ /**
21
+ * prepareSite()'s options (the folder and base URL come from Astro's config), whether to minify the
22
+ * site's own shaders (true), and whether to put Umber's chunks in the site (true; `false` loads them
23
+ * from umber.occluze.com).
24
+ */
25
+ export type UmberAstroOptions = Omit<SiteOptions, "dir" | "baseUrl" | "log"> & { shaders?: boolean; chunks?: boolean };
26
+
27
+ /** An Astro integration. */
28
+ export interface UmberAstroIntegration {
29
+ name: "@occluze/umber";
30
+ 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>;
37
+ };
38
+ }
39
+
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
@@ -1,27 +1,28 @@
1
- // -----------------------------------------
2
- // UMBER MODULE: DEBUG, TYPES (@occluze/umber/debug)
3
- // -----------------------------------------
4
-
5
- // The HUD, plane outlines and scroll markers. Load it while you build:
6
- //
7
- // import { Debug } from "@occluze/umber/debug";
8
- // gl.use(Debug, { outlines: true, markers: true });
9
- //
10
- // <script src=".../umber@x.y.z/modules/debug.js" data-outlines data-markers></script>
11
- //
12
- // ?umber-debug=hud,outlines,markers in the URL picks the parts too.
1
+ /**
2
+ * Types for the debug module (@occluze/umber/debug).
3
+ *
4
+ * The HUD, plane outlines and scroll markers. Load it while you build:
5
+ *
6
+ * import { Debug } from "@occluze/umber/debug";
7
+ * umber.use(Debug, { outlines: true, markers: true });
8
+ *
9
+ * <script src=".../umber@x.y.z/modules/debug.js" data-outlines data-markers></script>
10
+ *
11
+ * ?umber-debug=hud,outlines,markers in the URL picks the parts too.
12
+ */
13
13
 
14
- import type { DebugOptions, GL, UmberModule } from "./umber.js";
14
+ import type { DebugOptions, Umber, UmberModule } from "./umber.js";
15
15
 
16
16
  export type { DebugOptions };
17
17
 
18
- /** gl.use(Debug, options), createGL({ modules: [Debug], debug: { outlines: true } }). */
18
+ /** umber.use(Debug, options), createUmber({ modules: [Debug], debug: { outlines: true } }). */
19
19
  export declare const Debug: UmberModule;
20
20
 
21
21
  /**
22
- * The same without gl.use(): mounts the parts for `engine` and returns destroy().
22
+ * The same without umber.use(): mounts the parts for `engine` and returns destroy().
23
23
  * @example const stop = debug(gl, { outlines: true }); stop();
24
24
  */
25
- export declare function debug(engine: GL, options?: DebugOptions): () => void;
25
+ export declare function debug(engine: Umber, options?: DebugOptions): () => void;
26
26
 
27
+ /** @alias The same module as the named export, for `import Debug from`. */
27
28
  export default Debug;
package/types/esm.d.ts CHANGED
@@ -1,20 +1,20 @@
1
- // -----------------------------------------
2
- // UMBER: TYPES FOR THE NPM PACKAGE
3
- // -----------------------------------------
1
+ /**
2
+ * Types for the npm package entry (@occluze/umber).
3
+ *
4
+ * What `import { createUmber } from "@occluze/umber"` gives you (dist/umber.mjs,
5
+ * src/esm.ts). Every type comes from umber.d.ts (the same API as window.Umber).
6
+ *
7
+ * import { createUmber } from "@occluze/umber";
8
+ * import type { GL, UmberOptions, EffectDef } from "@occluze/umber";
9
+ */
4
10
 
5
- // What `import { createGL } from "@occluze/umber"` gives you (dist/umber.mjs,
6
- // src/esm.ts). Every type comes from umber.d.ts (the same API as window.Umber).
7
- //
8
- // import { createGL } from "@occluze/umber";
9
- // import type { GL, GLOptions, EffectDef } from "@occluze/umber";
10
-
11
- import type { GL, GLOptions, UmberMath } from "./umber.js";
11
+ import type { Umber, UmberOptions, UmberMath } from "./umber.js";
12
12
 
13
13
  export * from "./umber.js";
14
14
 
15
15
  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
- export declare function createGL(options?: GLOptions): GL;
17
+ export declare function createUmber(options?: UmberOptions): Umber;
18
18
 
19
19
  /** DOM <-> three.js maths (pure functions, no engine needed). */
20
20
  export declare const pxPerWorld: UmberMath["pxPerWorld"];
@@ -29,5 +29,5 @@ export declare const smoothstep: UmberMath["smoothstep"];
29
29
  export declare const rectProgress: UmberMath["rectProgress"];
30
30
  export declare const math: UmberMath;
31
31
 
32
- declare const Umber: { readonly version: string; createGL(options?: GLOptions): GL; readonly math: UmberMath };
32
+ declare const Umber: { readonly version: string; createUmber(options?: UmberOptions): Umber; readonly math: UmberMath };
33
33
  export default Umber;
@@ -0,0 +1,17 @@
1
+ /**
2
+ * The <script> tag's globals: window.Umber and `Umber`, which dist/umber.js sets (src/umber.ts).
3
+ *
4
+ * Only for sites that load umber.js with a tag: copy this file next to umber.d.ts, or, with
5
+ * the npm package installed, add /// <reference types="@occluze/umber/global" />. The npm
6
+ * entry (types/esm.d.ts) leaves it out, since `import { createUmber } from "@occluze/umber"`
7
+ * never sets window.Umber.
8
+ */
9
+
10
+ import type { UmberGlobal } from "./umber.js";
11
+
12
+ declare global {
13
+ interface Window {
14
+ Umber: UmberGlobal;
15
+ }
16
+ const Umber: UmberGlobal;
17
+ }