@occluze/umber 0.2.1 → 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.
Files changed (82) hide show
  1. package/LICENSE.md +21 -0
  2. package/README.md +126 -50
  3. package/THIRD-PARTY-NOTICES.md +33 -0
  4. package/dist/chunks/badge.js +2 -0
  5. package/dist/chunks/basis.js +2 -0
  6. package/dist/chunks/basis_transcoder.js +2 -0
  7. package/dist/chunks/basis_transcoder.wasm +0 -0
  8. package/dist/chunks/batches.js +2 -0
  9. package/dist/chunks/capture.js +2 -2
  10. package/dist/chunks/covers.js +2 -2
  11. package/dist/chunks/curves.js +2 -0
  12. package/dist/chunks/flip.js +2 -2
  13. package/dist/chunks/fx.js +2 -102
  14. package/dist/chunks/gl.js +2 -180
  15. package/dist/chunks/glsl.js +2 -239
  16. package/dist/chunks/glyphs.js +2 -0
  17. package/dist/chunks/inspect.js +2 -6
  18. package/dist/chunks/instances.js +2 -93
  19. package/dist/chunks/layers.js +2 -21
  20. package/dist/chunks/licence.js +2 -2
  21. package/dist/chunks/morph.js +2 -2
  22. package/dist/chunks/pace.js +2 -0
  23. package/dist/chunks/patch.js +2 -0
  24. package/dist/chunks/prepared.js +2 -0
  25. package/dist/chunks/profiler.js +2 -0
  26. package/dist/chunks/recheck.js +2 -0
  27. package/dist/chunks/resize.js +2 -0
  28. package/dist/chunks/restore.js +2 -2
  29. package/dist/chunks/shapes.js +2 -2
  30. package/dist/chunks/sim.js +2 -22
  31. package/dist/chunks/text.js +2 -52
  32. package/dist/chunks/video.js +2 -2
  33. package/dist/chunks/vocabulary.js +2 -0
  34. package/dist/chunks/warm.js +2 -2
  35. package/dist/modules/debug.js +2 -36
  36. package/dist/modules/debug.mjs +2 -36
  37. package/dist/modules/handoff.js +2 -2
  38. package/dist/modules/handoff.mjs +2 -2
  39. package/dist/modules/input.js +2 -2
  40. package/dist/modules/input.mjs +2 -2
  41. package/dist/modules/scrollfx.js +2 -0
  42. package/dist/modules/scrollfx.mjs +2 -0
  43. package/dist/modules/scrub.js +2 -8
  44. package/dist/modules/scrub.mjs +2 -8
  45. package/dist/modules/three.js +2 -0
  46. package/dist/modules/three.mjs +2 -0
  47. package/dist/node/assets.mjs +11 -0
  48. package/dist/node/astro.mjs +55 -0
  49. package/dist/node/cli.mjs +162 -0
  50. package/dist/node/shared-P6KINBNR.mjs +2113 -0
  51. package/dist/node/shared-VQKZUUXF.mjs +289 -0
  52. package/dist/node/vite.mjs +14 -0
  53. package/dist/prepared.mjs +2 -0
  54. package/dist/umber.css +2 -2
  55. package/dist/umber.js +2 -2
  56. package/dist/umber.mjs +2 -2
  57. package/docs/AI-quick.md +104 -86
  58. package/docs/AI.md +2299 -1692
  59. package/docs/npm.md +40 -32
  60. package/package.json +176 -24
  61. package/types/assets.d.ts +192 -0
  62. package/types/astro.d.ts +40 -0
  63. package/types/debug.d.ts +18 -17
  64. package/types/esm.d.ts +13 -17
  65. package/types/global.d.ts +17 -0
  66. package/types/handoff.d.ts +26 -25
  67. package/types/input.d.ts +63 -55
  68. package/types/loop.d.ts +87 -0
  69. package/types/module.d.ts +106 -0
  70. package/types/scrollfx.d.ts +44 -0
  71. package/types/scrub.d.ts +33 -32
  72. package/types/three.d.ts +251 -0
  73. package/types/umber.d.ts +705 -432
  74. package/types/vite.d.ts +33 -0
  75. package/dist/chunks/views.js +0 -2
  76. package/dist/modules/router-swap.js +0 -13
  77. package/dist/modules/router.js +0 -2
  78. package/dist/modules/router.mjs +0 -2
  79. package/dist/modules/scroll.js +0 -2
  80. package/dist/modules/scroll.mjs +0 -2
  81. package/types/router.d.ts +0 -181
  82. package/types/scroll.d.ts +0 -132
package/docs/npm.md CHANGED
@@ -1,69 +1,77 @@
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
 
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" })`. 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.2.1 (docs/npm.md)
20
- import { createGL } from "@occluze/umber";
19
+ // npm install --save-exact @occluze/umber@0.4.0
20
+ import { createUmber } from "@occluze/umber";
21
21
  import "@occluze/umber/umber.css";
22
- import { Scrub } from "@occluze/umber/scrub"; // optional module
23
22
 
24
- const gl = createGL({ modules: [Scrub] }); // 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;" } });
25
26
  ```
26
27
  <!-- /snippet -->
27
28
 
28
29
  ```js
29
30
  // src/site.js (runs in the browser). Your libraries stay yours: Umber never imports them.
30
- import Lenis from "lenis";
31
- import barba from "@barba/core";
32
- import { createGL } from "@occluze/umber";
31
+ import "./scroller.js"; // your smooth scroller, set up as its docs say
32
+ import "./router.js"; // your router, the same
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
- const lenis = new Lenis({ autoRaf: true });
37
- const gl = createGL({ scroll: lenis, modules: import.meta.env.DEV ? [Debug] : [] });
38
- gl.effect("dissolve", dissolve);
39
- barba.init({ /* your transitions */ });
37
+ const umber = createUmber({ modules: import.meta.env.DEV ? [Debug] : [] }); // nothing of the scroller or the router is passed
38
+ umber.effect("dissolve", dissolve);
40
39
  ```
41
40
 
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)).
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" />`.
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).
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.
44
+ - **No effects ship in the package.** You write them with `umber.effect()` ("Writing effects" in [AI.md](AI.md)).
46
45
 
47
- ## The GL chunk still comes from the CDN
46
+ ## Where the chunks come from
48
47
 
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:
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.
50
49
 
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):
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
- ```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: "..." }
52
+ ```
53
+ /assets/umber-*
54
+ Cache-Control: public, max-age=31536000, immutable
58
55
  ```
59
56
 
60
- Keep the version in that URL the same as the package version.
57
+ - **Any other bundler:** from the CDN folder of the package's version, `https://umber.occluze.com/umber@<version>/`.
58
+ - **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:
59
+
60
+ ```bash
61
+ mkdir -p public/umber@x.y.z
62
+ cp -r node_modules/@occluze/umber/dist/chunks public/umber@x.y.z/
63
+ ```
64
+
65
+ ```js
66
+ import { createUmber } from "@occluze/umber";
67
+ createUmber({ base: "/umber@x.y.z/" });
68
+ // or, before createUmber() runs: window.UmberConfig = { base: "/umber@x.y.z/" }
69
+ ```
61
70
 
62
- Self-hosting instead: copy `node_modules/@occluze/umber/dist/` to your public folder and set `base` to that folder.
71
+ `base` (or `window.UmberConfig.base`) wins over the plugin's folder and the CDN alike.
63
72
 
64
73
  ## Honest limits
65
74
 
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.
69
- - **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.
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.
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.
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.
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.4.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",
@@ -41,39 +44,79 @@
41
44
  "import": "./dist/modules/handoff.mjs",
42
45
  "default": "./dist/modules/handoff.mjs"
43
46
  },
44
- "./scroll": {
45
- "types": "./types/scroll.d.ts",
46
- "import": "./dist/modules/scroll.mjs",
47
- "default": "./dist/modules/scroll.mjs"
47
+ "./scrollfx": {
48
+ "types": "./types/scrollfx.d.ts",
49
+ "import": "./dist/modules/scrollfx.mjs",
50
+ "default": "./dist/modules/scrollfx.mjs"
51
+ },
52
+ "./astro": {
53
+ "types": "./types/astro.d.ts",
54
+ "import": "./dist/node/astro.mjs",
55
+ "default": "./dist/node/astro.mjs"
56
+ },
57
+ "./module": {
58
+ "types": "./types/module.d.ts"
59
+ },
60
+ "./three": {
61
+ "types": "./types/three.d.ts",
62
+ "import": "./dist/modules/three.mjs",
63
+ "default": "./dist/modules/three.mjs"
48
64
  },
49
- "./router": {
50
- "types": "./types/router.d.ts",
51
- "import": "./dist/modules/router.mjs",
52
- "default": "./dist/modules/router.mjs"
65
+ "./prepared": {
66
+ "types": "./types/prepared.d.ts",
67
+ "import": "./dist/prepared.mjs",
68
+ "default": "./dist/prepared.mjs"
53
69
  },
54
70
  "./umber.css": "./dist/umber.css",
55
71
  "./umber.js": "./dist/umber.js",
56
- "./types": "./types/umber.d.ts",
72
+ "./types": {
73
+ "types": "./types/umber.d.ts"
74
+ },
75
+ "./global": {
76
+ "types": "./types/global.d.ts"
77
+ },
78
+ "./assets": {
79
+ "types": "./types/assets.d.ts",
80
+ "import": "./dist/node/assets.mjs",
81
+ "default": "./dist/node/assets.mjs"
82
+ },
83
+ "./vite": {
84
+ "types": "./types/vite.d.ts",
85
+ "import": "./dist/node/vite.mjs",
86
+ "default": "./dist/node/vite.mjs"
87
+ },
57
88
  "./package.json": "./package.json"
58
89
  },
59
90
  "files": [
91
+ "LICENSE.md",
92
+ "THIRD-PARTY-NOTICES.md",
60
93
  "dist/umber.mjs",
94
+ "dist/prepared.mjs",
61
95
  "dist/umber.js",
62
96
  "dist/umber.css",
63
97
  "dist/chunks/*.js",
98
+ "dist/chunks/*.wasm",
64
99
  "dist/modules/*.js",
65
100
  "dist/modules/*.mjs",
101
+ "dist/node/*.mjs",
66
102
  "types/umber.d.ts",
103
+ "types/global.d.ts",
67
104
  "types/esm.d.ts",
68
105
  "types/scrub.d.ts",
69
106
  "types/debug.d.ts",
70
107
  "types/input.d.ts",
71
108
  "types/handoff.d.ts",
72
- "types/scroll.d.ts",
73
- "types/router.d.ts",
109
+ "types/scrollfx.d.ts",
110
+ "types/astro.d.ts",
111
+ "types/three.d.ts",
112
+ "types/module.d.ts",
113
+ "types/loop.d.ts",
74
114
  "docs/npm.md",
75
115
  "docs/AI.md",
76
- "docs/AI-quick.md"
116
+ "docs/AI-quick.md",
117
+ "types/assets.d.ts",
118
+ "types/vite.d.ts",
119
+ "types/astro.d.ts"
77
120
  ],
78
121
  "sideEffects": [
79
122
  "*.css",
@@ -82,19 +125,33 @@
82
125
  "./dist/modules/debug.js",
83
126
  "./dist/modules/input.js",
84
127
  "./dist/modules/handoff.js",
85
- "./dist/modules/scroll.js",
86
- "./dist/modules/router.js"
128
+ "./dist/modules/scrollfx.js",
129
+ "./dist/modules/three.js"
87
130
  ],
88
131
  "publishConfig": {
89
132
  "registry": "https://registry.npmjs.org",
90
133
  "access": "public"
91
134
  },
135
+ "peerDependencies": {
136
+ "three": ">=0.160.0"
137
+ },
138
+ "peerDependenciesMeta": {
139
+ "three": {
140
+ "optional": true
141
+ }
142
+ },
92
143
  "scripts": {
93
144
  "build": "node scripts/build.mjs && node scripts/docs.mjs",
94
145
  "dev": "node scripts/build.mjs --watch --serve",
95
- "typecheck": "tsc --noEmit",
96
- "test": "vitest run",
146
+ "typecheck": "tsc -b",
147
+ "test": "vitest run --config .config/vitest.config.mjs --project unit --coverage && vitest run --config .config/vitest.config.mjs --project dist",
148
+ "lint": "eslint .",
149
+ "format:check": "prettier --check .",
150
+ "knip": "knip",
151
+ "deps": "depcruise src --config .config/dependency-cruiser.cjs",
152
+ "check": "npm run typecheck && npm run lint && npm run format:check && npm test && npm run knip && npm run deps",
97
153
  "check:browser": "node test/browser/all.mjs",
154
+ "check:browser:changed": "node test/browser/changed.mjs",
98
155
  "check:oracle": "node test/browser/oracle.mjs",
99
156
  "check:render": "node test/browser/render.mjs",
100
157
  "check:idle": "node test/browser/idle.mjs",
@@ -103,20 +160,115 @@
103
160
  "check:glsl": "node test/browser/glsl.mjs",
104
161
  "check:stress": "node test/browser/stress.mjs",
105
162
  "check:capture": "node test/browser/capture.mjs",
106
- "check:router": "node test/browser/router.mjs",
163
+ "check:modules": "node test/browser/modules.mjs",
164
+ "check:fade": "node test/browser/fade.mjs",
165
+ "check:plug": "node test/browser/plug.mjs",
166
+ "check:vertex": "node test/browser/vertex.mjs",
167
+ "check:clock": "node test/browser/clock.mjs",
168
+ "check:scrollers": "node test/browser/scrollers.mjs",
169
+ "check:routers": "node test/browser/routers.mjs",
170
+ "check:three": "node test/browser/three.mjs",
171
+ "check:pictures": "node test/browser/pictures.mjs",
172
+ "check:licence": "node test/browser/licence.mjs",
173
+ "check:csp": "node test/browser/csp.mjs",
174
+ "check:curves": "node test/browser/curves.mjs",
175
+ "check:tiny": "node test/browser/tiny.mjs",
176
+ "check:scale": "node test/browser/scale.mjs",
177
+ "check:motion": "node test/browser/motion.mjs",
107
178
  "scrub": "node scripts/scrub.mjs",
108
179
  "release": "node deploy/release.mjs",
109
- "deploy": "cd deploy && wrangler pages deploy site --project-name umber --branch main",
110
- "prepublishOnly": "npm run build"
180
+ "deploy": "node deploy/deploy.mjs",
181
+ "deploy:staging": "node deploy/deploy.mjs --staging",
182
+ "prepublishOnly": "npm run build",
183
+ "prepare": "simple-git-hooks",
184
+ "build:native": "node scripts/native.mjs",
185
+ "test:native": "cargo test --manifest-path crates/Cargo.toml"
111
186
  },
112
187
  "devDependencies": {
188
+ "@eslint/js": "10.0.1",
189
+ "@types/node": "22.20.5",
190
+ "@types/three": "0.178.1",
191
+ "@vitest/coverage-v8": "4.1.12",
192
+ "acorn": "8.19.0",
193
+ "dependency-cruiser": "18.7.2",
113
194
  "esbuild": "0.25.10",
114
- "happy-dom": "18.0.1",
195
+ "eslint": "10.14.0",
196
+ "eslint-plugin-sonarjs": "4.2.2",
197
+ "globals": "17.14.0",
198
+ "happy-dom": "21.0.4",
199
+ "knip": "6.44.1",
115
200
  "lenis": "1.3.23",
116
201
  "pixelmatch": "7.2.0",
117
202
  "playwright": "1.63.0",
203
+ "prettier": "3.9.10",
204
+ "simple-git-hooks": "2.14.0",
205
+ "tempus": "1.0.0",
206
+ "terser": "5.51.2",
207
+ "three": "0.178.0",
118
208
  "typescript": "5.9.3",
119
- "vitest": "3.2.4",
209
+ "typescript-eslint": "8.72.1",
210
+ "vitest": "4.1.12",
120
211
  "wrangler": "4.156.2"
212
+ },
213
+ "simple-git-hooks": {
214
+ "pre-commit": "npm run check",
215
+ "commit-msg": "node scripts/commit-msg.mjs \"$1\""
216
+ },
217
+ "overrides": {
218
+ "minimatch": "11.0.5"
219
+ },
220
+ "prettier": {
221
+ "printWidth": 120
222
+ },
223
+ "knip": {
224
+ "entry": [
225
+ "src/umber.ts",
226
+ "src/esm.ts",
227
+ "src/prepared.ts",
228
+ "src/umber.css",
229
+ "src/gl/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",
231
+ "src/modules/*/{index,from-script}.ts",
232
+ "types/*.d.ts",
233
+ "scripts/*.mjs",
234
+ "deploy/*.mjs",
235
+ "deploy/functions/**/*.js",
236
+ "test/browser/*.mjs",
237
+ "test/browser/fixtures/*.js",
238
+ "test/browser/clock/*.js",
239
+ "test/browser/scrollers/*.js",
240
+ "test/browser/routers/*.js",
241
+ "test/browser/csp/*.js",
242
+ "test/browser/csp/site/*.js",
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",
249
+ "test/dist/*.ts",
250
+ "tools/assets/{cli,index,vite,astro}.ts"
251
+ ],
252
+ "project": [
253
+ "src/**/*.ts",
254
+ "types/**/*.ts",
255
+ "scripts/**/*.{mjs,mts}",
256
+ "deploy/**/*.{mjs,js}",
257
+ "test/**/*.{ts,mjs,js}",
258
+ "tools/**/*.ts"
259
+ ],
260
+ "ignoreDependencies": [
261
+ "lenis",
262
+ "tempus",
263
+ "wrangler"
264
+ ]
265
+ },
266
+ "optionalDependencies": {
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"
121
273
  }
122
274
  }
@@ -0,0 +1,192 @@
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 (38.75 for an opaque picture, 40 for one with alpha): 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 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
+
58
+ /** What prepareSite() is given. */
59
+ export interface SiteOptions extends PrepareOptions {
60
+ /** The built site's folder. */
61
+ dir: string;
62
+ /** The URL path the folder is served at ("/", or the site's base, "/docs/"). */
63
+ baseUrl?: string;
64
+ /** The folder inside `dir` the prepared files go to ("_umber"). */
65
+ folder?: string;
66
+ /** Every picture file in `dir`, not only the ones a page has Umber draw. */
67
+ all?: boolean;
68
+ /**
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).
109
+ */
110
+ fonts?: boolean;
111
+ /**
112
+ * What the page's own <img> of a prepared picture shows. "tiny" (the default): a small
113
+ * placeholder AVIF while GL loads, so a visitor whose GPU draws the picture downloads that
114
+ * and the GPU file only; wherever GL won't draw it (no WebGL2, GL off, printing, Umber's
115
+ * script not running 3 s after the page loaded) the <img> loads the full AVIF in its place, at
116
+ * the same size. "avif": the picture's AVIF when that is smaller, so the page downloads it
117
+ * and the GPU file instead of the full file too. "source": the file as it was. The <img>'s
118
+ * own src never changes, so search engines index the original picture.
119
+ */
120
+ domImages?: "tiny" | "avif" | "source";
121
+ /** domImages "tiny": the placeholder's longer side, px, a whole number from 16 to 4096 (512). */
122
+ tinySize?: number;
123
+ /** domImages "tiny": the placeholder's AVIF quality, 1 to 100 (50). */
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>;
140
+ /** Where prepared files are kept between builds, so an unchanged picture is not made again; false for none ("node_modules/.cache/umber-assets"). */
141
+ cache?: string | false;
142
+ /** Where progress goes, one line each (nowhere by default). */
143
+ log?: (line: string) => void;
144
+ }
145
+
146
+ /** What prepareSite() did. */
147
+ export interface SiteResult {
148
+ /** The manifest's URL (what each page's `<meta name="umber-assets">` points at), or null when no page has a picture Umber draws. */
149
+ manifest: string | null;
150
+ /** Pictures prepared now. */
151
+ prepared: number;
152
+ /** Pictures taken from the cache. */
153
+ cached: number;
154
+ /** Pages that got the meta tag. */
155
+ pages: number;
156
+ /** Fonts prepared for GL text painted from their outlines. */
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;
166
+ /** Pictures a page names that are not in the folder (another site's, or missing), and pictures that failed, with why. */
167
+ skipped: string[];
168
+ /** Bytes written per kind ("bc7", "astc", "etc2", "avif"), and of the source pictures ("source"). */
169
+ bytes: Record<string, number>;
170
+ }
171
+
172
+ /**
173
+ * Prepare the pictures Umber draws on a built site (the `<img>`, `srcset` and `data-umber-src`
174
+ * inside `[data-umber]` elements): BC7, ASTC and ETC2 textures with all their mip levels and an
175
+ * AVIF in `<dir>/_umber/`, a manifest next to them, and `<meta name="umber-assets">` on every
176
+ * page that shows one. The HTML stays as it was otherwise.
177
+ */
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>>;
@@ -0,0 +1,40 @@
1
+ /**
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'`.
8
+ *
9
+ * import umberAstro from "@occluze/umber/astro";
10
+ * export default defineConfig({ integrations: [umberAstro()] });
11
+ */
12
+
13
+ import type { SiteOptions } from "./assets.js";
14
+
15
+ /**
16
+ * prepareSite()'s options (the folder and base URL come from Astro's config), whether to minify the
17
+ * site's own shaders (true), and whether to put Umber's chunks in the site (true; `false` loads them
18
+ * from umber.occluze.com).
19
+ */
20
+ export type UmberAstroOptions = Omit<SiteOptions, "dir" | "baseUrl" | "log"> & { shaders?: boolean; chunks?: boolean };
21
+
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`. */
31
+ export interface UmberAstroIntegration {
32
+ name: string;
33
+ hooks: {
34
+ "astro:config:setup": AstroHook;
35
+ "astro:config:done": AstroHook;
36
+ "astro:build:done": AstroHook;
37
+ };
38
+ }
39
+
40
+ export default function umberAstro(options?: UmberAstroOptions): UmberAstroIntegration;