@kerf-js/keel 0.0.0-stage → 0.1.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 (192) hide show
  1. package/LICENSE +16 -0
  2. package/README.md +306 -2
  3. package/package.json +59 -3
  4. package/src/blend-inset.ts +79 -0
  5. package/src/blend.ts +120 -0
  6. package/src/client.d.ts +9 -0
  7. package/src/generate/bust.ts +24 -0
  8. package/src/generate/bust.worker.ts +4 -0
  9. package/src/generate/pack.ts +69 -0
  10. package/src/generate/plate.ts +51 -0
  11. package/src/generate/plate.worker.ts +4 -0
  12. package/src/generate/serve.ts +56 -0
  13. package/src/generate/surface.ts +16 -0
  14. package/src/generate/surface.worker.ts +4 -0
  15. package/src/generate.ts +133 -0
  16. package/src/governor.ts +87 -0
  17. package/src/index.d.ts +15 -0
  18. package/src/index.mjs +63 -0
  19. package/src/lit.d.ts +384 -0
  20. package/src/paint-live.ts +60 -0
  21. package/src/paint-recipe.d.mts +29 -0
  22. package/src/paint-recipe.mjs +29 -0
  23. package/src/paint-worker.mjs +20 -0
  24. package/src/paint.d.mts +37 -0
  25. package/src/paint.mjs +180 -0
  26. package/src/runtime.ts +35 -0
  27. package/src/scene.ts +289 -0
  28. package/src/stage.ts +192 -0
  29. package/vendor/LICENSE +21 -0
  30. package/vendor/LICENSE-modules +21 -0
  31. package/vendor/NOTICE +24 -0
  32. package/vendor/README.md +13 -0
  33. package/vendor/lit.d.mts +1 -0
  34. package/vendor/lit.mjs +2 -0
  35. package/vendor/lock.json +177 -0
  36. package/vendor/modules/band/events.d.ts +20 -0
  37. package/vendor/modules/band/index.d.ts +29 -0
  38. package/vendor/modules/band/player.d.ts +43 -0
  39. package/vendor/modules/band/roll.d.ts +14 -0
  40. package/vendor/modules/band/score.d.ts +45 -0
  41. package/vendor/modules/band/styles.data.d.ts +37 -0
  42. package/vendor/modules/band/voices.d.ts +33 -0
  43. package/vendor/modules/band.d.mts +1 -0
  44. package/vendor/modules/band.mjs +2 -0
  45. package/vendor/modules/butterflies/butterflies.glsl.d.ts +2 -0
  46. package/vendor/modules/butterflies/flight.d.ts +68 -0
  47. package/vendor/modules/butterflies/index.d.ts +79 -0
  48. package/vendor/modules/butterflies/wing.d.ts +38 -0
  49. package/vendor/modules/butterflies.d.mts +1 -0
  50. package/vendor/modules/butterflies.inputs.json +73 -0
  51. package/vendor/modules/butterflies.mjs +39 -0
  52. package/vendor/modules/camera-rail/index.d.ts +113 -0
  53. package/vendor/modules/camera-rail.d.mts +1 -0
  54. package/vendor/modules/camera-rail.mjs +2 -0
  55. package/vendor/modules/device-profile/index.d.ts +47 -0
  56. package/vendor/modules/device-profile.d.mts +1 -0
  57. package/vendor/modules/device-profile.mjs +2 -0
  58. package/vendor/modules/lit-finish/dress.d.ts +34 -0
  59. package/vendor/modules/lit-finish/finish.glsl.d.ts +15 -0
  60. package/vendor/modules/lit-finish/index.d.ts +33 -0
  61. package/vendor/modules/lit-finish/lit.d.ts +52 -0
  62. package/vendor/modules/lit-finish/pass.d.ts +35 -0
  63. package/vendor/modules/lit-finish/settings.d.ts +88 -0
  64. package/vendor/modules/lit-finish.d.mts +1 -0
  65. package/vendor/modules/lit-finish.inputs.json +200 -0
  66. package/vendor/modules/lit-finish.mjs +267 -0
  67. package/vendor/modules/look/index.d.ts +159 -0
  68. package/vendor/modules/look.d.mts +1 -0
  69. package/vendor/modules/look.inputs.json +23 -0
  70. package/vendor/modules/look.mjs +2 -0
  71. package/vendor/modules/motes/index.d.ts +83 -0
  72. package/vendor/modules/motes/motes.glsl.d.ts +9 -0
  73. package/vendor/modules/motes/place.d.ts +59 -0
  74. package/vendor/modules/motes.d.mts +1 -0
  75. package/vendor/modules/motes.inputs.json +116 -0
  76. package/vendor/modules/motes.mjs +68 -0
  77. package/vendor/modules/plate-painter/dab.d.ts +44 -0
  78. package/vendor/modules/plate-painter/exact.d.ts +19 -0
  79. package/vendor/modules/plate-painter/foliage.d.ts +4 -0
  80. package/vendor/modules/plate-painter/gpu.d.ts +65 -0
  81. package/vendor/modules/plate-painter/index.d.ts +14 -0
  82. package/vendor/modules/plate-painter/paint.glsl.d.ts +14 -0
  83. package/vendor/modules/plate-painter/plan.d.ts +42 -0
  84. package/vendor/modules/plate-painter/recipe.d.ts +136 -0
  85. package/vendor/modules/plate-painter/scene.d.ts +4 -0
  86. package/vendor/modules/plate-painter.d.mts +1 -0
  87. package/vendor/modules/plate-painter.inputs.json +50 -0
  88. package/vendor/modules/plate-painter.mjs +384 -0
  89. package/vendor/modules/portrait/body.d.ts +25 -0
  90. package/vendor/modules/portrait/bust.d.ts +67 -0
  91. package/vendor/modules/portrait/cap.d.ts +12 -0
  92. package/vendor/modules/portrait/compile.d.ts +8 -0
  93. package/vendor/modules/portrait/exact.d.ts +17 -0
  94. package/vendor/modules/portrait/hair.d.ts +26 -0
  95. package/vendor/modules/portrait/hand.d.ts +30 -0
  96. package/vendor/modules/portrait/head.d.ts +18 -0
  97. package/vendor/modules/portrait/index.d.ts +12 -0
  98. package/vendor/modules/portrait/mesh.d.ts +24 -0
  99. package/vendor/modules/portrait/parts.d.ts +33 -0
  100. package/vendor/modules/portrait/portrait.glsl.d.ts +4 -0
  101. package/vendor/modules/portrait/render.d.ts +125 -0
  102. package/vendor/modules/portrait/sdf.d.ts +75 -0
  103. package/vendor/modules/portrait/settings.d.ts +27 -0
  104. package/vendor/modules/portrait.d.mts +1 -0
  105. package/vendor/modules/portrait.inputs.json +111 -0
  106. package/vendor/modules/portrait.mjs +2 -0
  107. package/vendor/modules/quality/index.d.ts +130 -0
  108. package/vendor/modules/quality.d.mts +1 -0
  109. package/vendor/modules/quality.inputs.json +34 -0
  110. package/vendor/modules/quality.mjs +2 -0
  111. package/vendor/modules/scene-blend/blend.d.ts +54 -0
  112. package/vendor/modules/scene-blend/blend.glsl.d.ts +8 -0
  113. package/vendor/modules/scene-blend/index.d.ts +25 -0
  114. package/vendor/modules/scene-blend/lit.d.ts +61 -0
  115. package/vendor/modules/scene-blend/noise.d.ts +13 -0
  116. package/vendor/modules/scene-blend/settings.d.ts +63 -0
  117. package/vendor/modules/scene-blend.d.mts +1 -0
  118. package/vendor/modules/scene-blend.inputs.json +133 -0
  119. package/vendor/modules/scene-blend.mjs +2 -0
  120. package/vendor/modules/section-post/index.d.ts +23 -0
  121. package/vendor/modules/section-post/lit.d.ts +47 -0
  122. package/vendor/modules/section-post/noise.d.ts +14 -0
  123. package/vendor/modules/section-post/post.d.ts +31 -0
  124. package/vendor/modules/section-post/post.glsl.d.ts +8 -0
  125. package/vendor/modules/section-post/settings.d.ts +84 -0
  126. package/vendor/modules/section-post.d.mts +1 -0
  127. package/vendor/modules/section-post.inputs.json +107 -0
  128. package/vendor/modules/section-post.mjs +53 -0
  129. package/vendor/modules/surfaces/exact.d.ts +8 -0
  130. package/vendor/modules/surfaces/field.d.ts +7 -0
  131. package/vendor/modules/surfaces/gpu.d.ts +19 -0
  132. package/vendor/modules/surfaces/index.d.ts +17 -0
  133. package/vendor/modules/surfaces/paint.d.ts +28 -0
  134. package/vendor/modules/surfaces/plan.d.ts +39 -0
  135. package/vendor/modules/surfaces/print.d.ts +55 -0
  136. package/vendor/modules/surfaces/recipe.d.ts +143 -0
  137. package/vendor/modules/surfaces/surface.glsl.d.ts +4 -0
  138. package/vendor/modules/surfaces.d.mts +1 -0
  139. package/vendor/modules/surfaces.inputs.json +54 -0
  140. package/vendor/modules/surfaces.mjs +172 -0
  141. package/vendor/modules/tracks/index.d.ts +66 -0
  142. package/vendor/modules/tracks.d.mts +1 -0
  143. package/vendor/modules/tracks.mjs +2 -0
  144. package/vendor/modules/tree-growth/bend.d.ts +28 -0
  145. package/vendor/modules/tree-growth/frame.d.ts +60 -0
  146. package/vendor/modules/tree-growth/index.d.ts +23 -0
  147. package/vendor/modules/tree-growth/light.d.ts +13 -0
  148. package/vendor/modules/tree-growth/math.d.ts +19 -0
  149. package/vendor/modules/tree-growth/model.d.ts +100 -0
  150. package/vendor/modules/tree-growth/sectors.d.ts +10 -0
  151. package/vendor/modules/tree-growth/simulation.d.ts +58 -0
  152. package/vendor/modules/tree-growth/species.d.ts +117 -0
  153. package/vendor/modules/tree-growth/species.data.d.ts +2 -0
  154. package/vendor/modules/tree-growth/year.d.ts +38 -0
  155. package/vendor/modules/tree-growth.d.mts +1 -0
  156. package/vendor/modules/tree-growth.inputs.json +75 -0
  157. package/vendor/modules/tree-growth.mjs +2 -0
  158. package/vendor/modules/tree-render/features.d.ts +9 -0
  159. package/vendor/modules/tree-render/forest/bake.d.ts +41 -0
  160. package/vendor/modules/tree-render/forest/cards.d.ts +28 -0
  161. package/vendor/modules/tree-render/forest/forest.d.ts +156 -0
  162. package/vendor/modules/tree-render/index.d.ts +52 -0
  163. package/vendor/modules/tree-render/inputs.d.ts +260 -0
  164. package/vendor/modules/tree-render/instances.d.ts +66 -0
  165. package/vendor/modules/tree-render/math.d.ts +8 -0
  166. package/vendor/modules/tree-render/tree/bark.d.ts +20 -0
  167. package/vendor/modules/tree-render/tree/leaves.d.ts +29 -0
  168. package/vendor/modules/tree-render/tree/litter.d.ts +21 -0
  169. package/vendor/modules/tree-render/tree/ornaments.d.ts +36 -0
  170. package/vendor/modules/tree-render/tree/roots.d.ts +75 -0
  171. package/vendor/modules/tree-render/tree/shapes.d.ts +49 -0
  172. package/vendor/modules/tree-render/tree/tree.d.ts +239 -0
  173. package/vendor/modules/tree-render/tree/wood.d.ts +27 -0
  174. package/vendor/modules/tree-render/wind.d.ts +51 -0
  175. package/vendor/modules/tree-render.d.mts +1 -0
  176. package/vendor/modules/tree-render.inputs.json +45 -0
  177. package/vendor/modules/tree-render.mjs +2 -0
  178. package/vendor/modules/voxel-dither/dither.glsl.d.ts +9 -0
  179. package/vendor/modules/voxel-dither/index.d.ts +35 -0
  180. package/vendor/modules/voxel-dither/light.d.ts +33 -0
  181. package/vendor/modules/voxel-dither/lit.d.ts +86 -0
  182. package/vendor/modules/voxel-dither/pass.d.ts +46 -0
  183. package/vendor/modules/voxel-dither/screens.d.ts +21 -0
  184. package/vendor/modules/voxel-dither/settings.d.ts +307 -0
  185. package/vendor/modules/voxel-dither/signals.d.ts +35 -0
  186. package/vendor/modules/voxel-dither.d.mts +1 -0
  187. package/vendor/modules/voxel-dither.inputs.json +295 -0
  188. package/vendor/modules/voxel-dither.mjs +452 -0
  189. package/vendor/modules/world-light/index.d.ts +133 -0
  190. package/vendor/modules/world-light.d.mts +1 -0
  191. package/vendor/modules/world-light.inputs.json +68 -0
  192. package/vendor/modules/world-light.mjs +2 -0
package/LICENSE ADDED
@@ -0,0 +1,16 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ravonus
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
6
+ documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
7
+ rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
8
+ persons to whom the Software is furnished to do so, subject to the following conditions:
9
+
10
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
11
+ Software.
12
+
13
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
14
+ WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
15
+ COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
16
+ OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,307 @@
1
- # Temporary Holding Version
1
+ # @kerf-js/keel
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ KEEL generation for kerf. It adds the `keel-lit` surface kind, a lit WebGL2 scene with physically based
4
+ materials and soft shadows, and ships KEEL's generators as modules that load only where a page uses them.
5
+ Nothing is an authored asset: trees are grown from a seed, light is the sun's for a place and hour, and
6
+ music is scored from a seed.
7
+
8
+ ```ts
9
+ // kerf.config.ts
10
+ import { defineConfig } from '@kerf-js/core/config'
11
+ import { keel } from '@kerf-js/keel'
12
+
13
+ export default defineConfig({ plugins: [keel()] })
14
+ ```
15
+
16
+ ```tsx
17
+ import { defineSurface, Surface } from '@kerf-js/core/surface'
18
+ import { keelStage } from '@kerf-js/keel/stage'
19
+
20
+ export const Grove = defineSurface<{}, 'keel-lit'>({
21
+ name: 'grove',
22
+ kind: 'keel-lit',
23
+ setup(s) {
24
+ let draw = () => {}
25
+ void keelStage(s, { prefer: 'realism' }).then(async (stage) => {
26
+ const growth = await import(
27
+ '@kerf-js/keel/modules/tree-growth'
28
+ )
29
+ const { createTreeRender } = await import(
30
+ '@kerf-js/keel/modules/tree-render'
31
+ )
32
+ const model = growth.growTree({ species: 'oak', seed: 42 })
33
+ const tree = createTreeRender(s.lit as never, model, {
34
+ colors,
35
+ ground: { y: 0, radius: 4 },
36
+ })
37
+ stage.scene.add(tree.group)
38
+ stage.camera.position.set(0, 4, 14)
39
+ stage.camera.lookAt(0, 3, 0)
40
+ const year = growth.yearState({ species: 'oak', day: 170 })
41
+ const pose = growth.treeFrame(model, model.cycles * 0.8)
42
+ draw = () => {
43
+ const elapsed = s.clock.seconds
44
+ tree.update(pose, year, { elapsed, delta: 0, wind: 0.3 })
45
+ stage.render()
46
+ }
47
+ s.invalidate()
48
+ })
49
+ s.frame(() => draw())
50
+ },
51
+ })
52
+ ```
53
+
54
+ ## The surface kind
55
+
56
+ `kind: 'keel-lit'` gives `setup` two fields:
57
+
58
+ - `s.lit`: the keel/lit namespace. `Stage`, `Group`, `Mesh`, `Instances`, `PerspectiveCamera`, `SunLight`,
59
+ `SkyLight`, `LitMaterial`, `ToonMaterial`, `CustomMaterial`, geometry functions (`box()`, `sphere()`,
60
+ `plane()`, `lathe()`, `extrude()` and more), render targets, fog, and environment light:
61
+ `stage.environment = new Environment(STUDIO, { size: 128 })`, a generated studio with no file.
62
+ - `s.renderer`: its renderer, bound to the surface's canvas and sized with it.
63
+
64
+ The surface's own rules still hold: the server renders a sized placeholder, an off-screen surface skips its
65
+ paints, and under `prefers-reduced-motion: reduce` the clock starts paused on one still frame.
66
+
67
+ ## A stage with a look
68
+
69
+ `keelStage(s, options)` from `@kerf-js/keel/stage` sets up what most scenes need and draws them through
70
+ one look recipe (`keel-look@1`):
71
+
72
+ | | |
73
+ | --- | --- |
74
+ | `stage.scene`, `stage.camera`, `stage.sun`, `stage.sky` | Add to the scene; move the camera and lights. |
75
+ | `stage.setLook('realism' \| 'pixel', recipe?)` | The same scene in lit full colour (ambient occlusion, haze, bloom, a tone map and grade) or dithered pixel art. Each pass loads the first time its look is used. |
76
+ | `stage.light(worldLight(...))` | Sun, sky fill, background and air from `world-light`'s answer. |
77
+ | `stage.look` | What the look asks of generators: `density`, `trees`, `kind`. |
78
+ | `stage.render()` | Draws a frame. Call it inside `s.frame`. |
79
+
80
+ ## Modules
81
+
82
+ Each is `@kerf-js/keel/modules/<id>`, typed, and its own file: import it with `import()` and a page
83
+ that never reaches that line never downloads it.
84
+
85
+ | Module | What it makes |
86
+ | --- | --- |
87
+ | `tree-growth` | A tree grown from a species and a seed, posed for any age and day of the year. |
88
+ | `tree-render` | Draws that tree, or a forest of them with levels of detail and impostor cards. |
89
+ | `world-light` | The sun, moon, sky colours, fog and haze of a place and instant. |
90
+ | `look` | Resolves a `keel-look@1` recipe for a target. |
91
+ | `voxel-dither` | The dithered pixel look: palettes, screens, outlines, cel light. |
92
+ | `lit-finish` | The realism look: ambient occlusion, aerial haze, light through leaves, TAA, bloom, tone map, grade. |
93
+ | `band` | A seeded generative band in eight styles on plain Web Audio, layered by an energy dial. |
94
+ | `quality`, `device-profile` | Detail levels by device, a frame-time governor, and the page levers a scene spends. |
95
+ | `tracks` | Keyed tracks sampled at a position, eased by cubic-bezier handles. |
96
+ | `camera-rail` | A camera on keyed tracks, with pointer pan and tilt. |
97
+ | `scene-blend` | A hand-over between two lit scenes: line work and a seeded noise or radial reveal, or a plain fade. |
98
+ | `section-post` | A section's pass after the finish: a paper panel with a straight or torn edge, darkening, blur and grain. |
99
+ | `motes` | Dust, light motes and sparkles on one instanced quad, drifting and blinking on the page's clock. |
100
+ | `butterflies` | A small flock of glowing butterflies with Shape wings, wandering on a seed and the page's clock. |
101
+ | `plate-painter` | A painted landscape plate from a seeded recipe, generated on the GPU and drawn behind a scene. |
102
+ | `portrait` | A seeded waist-up portrait bust at hero detail, sculpted and meshed when generated, with soft portrait light. |
103
+ | `surfaces` | Seeded paper grain, rib knit and painted grounds as an albedo and a relief, on the GPU or the CPU; prints. |
104
+
105
+ `vendor/modules/<id>.inputs.json` lists the settings a module offers a host, as `keel-module-inputs@1`.
106
+
107
+ ## Scrubbing a scene
108
+
109
+ `@kerf-js/scroll/timeline` reads keyframe tracks at a position and follows a section's scroll progress:
110
+
111
+ ```ts
112
+ import { progress, timeline } from '@kerf-js/scroll/timeline'
113
+
114
+ const tracks = timeline({
115
+ z: [[0, 54], [1, 8]],
116
+ fov: [[0, 34], [1, 50]],
117
+ })
118
+ const scrub = progress(section, { onChange: () => s.invalidate() })
119
+ s.frame(() => {
120
+ const at = tracks.at(scrub.value)
121
+ stage.camera.position.set(0, 3, at.z)
122
+ })
123
+ ```
124
+
125
+ ## Scenes on a stage
126
+
127
+ `defineScene` from `@kerf-js/keel/scene` declares one section's scene for veneer's `<Stage>` and `<Scene>`
128
+ (`@kerf-js/veneer/scenes`), which share one canvas across the page:
129
+
130
+ ```ts
131
+ import { defineScene } from '@kerf-js/keel/scene'
132
+
133
+ export const orchard = defineScene({
134
+ tracks: [
135
+ {
136
+ target: 'camera',
137
+ property: 'eye',
138
+ keys: [[0, [0, 2, 9]], [2, [3, 2, 5]]],
139
+ },
140
+ { target: 'tree', property: 'sway', keys: [[0, 0], [2, 1]] },
141
+ ],
142
+ build({ lit }) {
143
+ const stage = new lit.Stage()
144
+ const camera = new lit.PerspectiveCamera(40, 1, 0.1, 100)
145
+ const tree = new lit.Group()
146
+ stage.add(tree, new lit.SkyLight('#fff', '#443', 1))
147
+ return { stage, camera, tree }
148
+ },
149
+ at(position, frame, values) {
150
+ this.tree.rotation.z = 0.1 * Number(values.tree?.sway ?? 0)
151
+ },
152
+ })
153
+ ```
154
+
155
+ The stage builds a scene when its section comes near and frees it two scenes away. Tracks that key a `camera`
156
+ target drive the camera through `camera-rail`; `at` gets the other sampled values, with `this` the object
157
+ `build` returned. A scene also takes `modules` (loaded before `build`), `setQuality(levers)`, `render()` for a
158
+ finish of its own and `dispose()`; the stage's meshes, materials and textures are freed for it. `hold` (a position, or
159
+ `'first'` or `'last'` for its tracks' first or last key) is where it stands under reduced motion and on a low tier,
160
+ where `keelGovernor()` holds scenes still.
161
+
162
+ `keelGovernor()` from `@kerf-js/keel/governor` is the stage's governor: `device-profile` picks the
163
+ tier, the tier the fps cap (30 on low) and the widest canvas (3840, 1920 or 1280 px), and `quality` the level,
164
+ its page levers (`quality.levers`) and a render scale it lowers while frames run slow:
165
+ `<Stage governor={keelGovernor()}>`.
166
+ `keelGovernor({ hold: '(max-width: 767px)' })` also holds scenes where a media query matches, so a phone stands
167
+ at each scene's `hold` with no camera override of its own.
168
+
169
+ `keelBlend()` from `@kerf-js/keel/blend` is the stage's blend: `<Stage blend={keelBlend()}>`. Every scene
170
+ is drawn through `lit-finish`. A hand-over goes through `scene-blend`: the incoming scene arrives as line work
171
+ and fills in through seeded noise, or out from its `<Scene centre>` with `mode="radial"`, and the less visible
172
+ scene is drawn by a lighter finish at the levers' `blendScale`. The active section's pass goes through
173
+ `section-post`: a paper panel with a straight or torn edge, and darkening and blur, from `<Scene post>` or from
174
+ tracks on a `post` target:
175
+
176
+ ```ts
177
+ tracks: [
178
+ {
179
+ target: 'post',
180
+ property: 'progress',
181
+ keys: [[1, 0], [2, 1], [3, 2]],
182
+ },
183
+ { target: 'post', property: 'tear', keys: [[0, 1]] },
184
+ ]
185
+ ```
186
+
187
+ `keelBlend({ finish, blend, post })` passes settings to each module: `blend: { seed: 7, lineColour: '#ffffff' }`.
188
+
189
+ A page whose own panel is a column keeps the paper to it with `inset`, CSS px from the frame's left and right
190
+ edges or a function of its size: `keelBlend({ inset: (width) => [width / 4, width / 4] })`. The strips beside
191
+ the column show the scene with no panel, darkening or blur.
192
+
193
+ ## Painted grounds
194
+
195
+ A seeded surface can be painted at build time and served as ordinary media. Add `keelPaint()` before kerf's
196
+ Vite plugin, and `media()` to `kerf.config.ts` for the AVIF ladder, a JPEG fallback and the placeholder:
197
+
198
+ ```json
199
+ {
200
+ "surface": "painted-floral",
201
+ "seed": 7,
202
+ "width": 1108,
203
+ "height": 700
204
+ }
205
+ ```
206
+
207
+ ```tsx
208
+ import floral from './floral.paint.json?paint'
209
+
210
+ <Media
211
+ src={floral}
212
+ alt=""
213
+ decorative
214
+ width="554px"
215
+ />
216
+ ```
217
+
218
+ A recipe names a preset (`paper`, `knit`, `painted-floral`, `painted-cloth`) with `with` laid over it, or
219
+ gives a whole `recipe`. The PNG is painted on the CPU, on worker threads so a page's recipes paint side by side
220
+ (`keelPaint({ threads })`, default one fewer than the cores up to 4), and kept in `.kerf/cache/paint` under the
221
+ plan's digest and the module's version, so a rebuild with the recipe unchanged paints nothing. Add
222
+ `"@kerf-js/keel/client"` to `types` for the `?paint` declaration. `paper` and `knit` tile: `cssImage`
223
+ from `paint-live` gives an `image-set` of each format's widest file, for `background-image`.
224
+
225
+ A colour or seed known only at run time is painted in a worker (see below), on a WebGL2 `OffscreenCanvas` or the
226
+ CPU, and encoded here:
227
+
228
+ ```ts
229
+ import { paintLive } from '@kerf-js/keel/paint-live'
230
+
231
+ const themed = await paintLive({
232
+ surface: 'painted-cloth',
233
+ seed: 12,
234
+ with: { ground: '#3a2347' },
235
+ })
236
+ ```
237
+
238
+ It gives a media record whose `src` is a blob URL; `themed.revoke()` frees it.
239
+
240
+ ## Generators off the main thread
241
+
242
+ A portrait's bust takes a few hundred ms to mesh, and a plate a frame's worth of GPU work and a read-back.
243
+ `generate` runs them in a worker and hands the result back with its buffers transferred:
244
+
245
+ ```ts
246
+ import { generate } from '@kerf-js/keel/generate'
247
+
248
+ const sitter = { seed: 7, face: 'A', detail: 'hero' } as const
249
+ const bust = await generate('bust', sitter)
250
+ const plate = await generate('plate', {
251
+ width: 1440,
252
+ height: 900,
253
+ })
254
+ const portrait = await import(
255
+ '@kerf-js/keel/modules/portrait'
256
+ )
257
+ const figure = portrait.createPortrait(lit, bust, bust.palette)
258
+ ```
259
+
260
+ The jobs are `bust` (portrait's settings or a recipe), `plate` (plate-painter's plate at a size, as pixels) and
261
+ `surface` (as `paintLive` takes it). A result is kept by its job and arguments, so asking again, from a page that
262
+ asks early and a scene's `build` that asks later, gives the same promise. A bust or surface is also kept in Cache
263
+ Storage under the worker's hashed file name, so a later visit reads it back (secure contexts, built pages);
264
+ `{ keep: false }` shares one only while it runs, as plates are by default. The data comes back; geometry and
265
+ textures are made here, on the renderer's thread. Without workers the job runs on this thread.
266
+
267
+ ## Music
268
+
269
+ ```ts
270
+ const { createBand, scoreOf } = await import(
271
+ '@kerf-js/keel/modules/band'
272
+ )
273
+ // From a click: browsers start audio only from a gesture.
274
+ const band = createBand(new AudioContext())
275
+ band.start(scoreOf({ seed: 'grove', style: 'dream' }))
276
+ band.setEnergy(0.4) // fewer parts
277
+ ```
278
+
279
+ Styles: `ambient`, `lofi`, `synthwave`, `chiptune`, `house`, `cinematic`, `folk`, `dream`. `scoreOf` and
280
+ `eventsAt` are pure, so a visual can read what plays at any sixteenth note and move with it.
281
+
282
+ ## The demo
283
+
284
+ `demo/` is a pinned grove scrubbed by the scroll: the camera flies in while spring turns to autumn and
285
+ morning to evening, in either look, with the band joining in as you go deeper. `demo/stage.html` is three sections over one
286
+ stage, each with a scene of its own, blending into the next as its section arrives, with a straight-edged paper
287
+ panel over the second scene and a torn one over the third. `stage.html?measure` times every frame drawn. Its
288
+ posters are baked from the scenes themselves with `@kerf-js/capture`, and a phone gets only them, with no renderer
289
+ loaded.
290
+
291
+ ```bash
292
+ node test/serve.mjs 4179
293
+ ```
294
+
295
+ `pnpm run test:e2e` runs it in Chrome on the GPU and checks its pixels. It also bakes the stage's posters,
296
+ rebuilds with them, and captures the stage at three scroll stops.
297
+
298
+ `demo/paint.html` shows two card grounds and a paper band painted at build, and a card painted in the page in
299
+ a theme's colour. `node test/paint-e2e.mjs` checks them and prints each rung's bytes.
300
+
301
+ `demo/sitter.html` builds a portrait and its plate in workers; `sitter.html?here` builds them on the main thread.
302
+ `node test/generate-e2e.mjs` compares the long tasks of the two and reads the bust back from Cache Storage.
303
+
304
+ ## Vendored code
305
+
306
+ `vendor/` is generated by `scripts/vendor.mjs` from pinned commits of keel-engine and keel-modules (both MIT)
307
+ and is held to `vendor/lock.json`. keel/lit ports Three.js r180 (MIT); see `vendor/NOTICE`.
package/package.json CHANGED
@@ -1,6 +1,62 @@
1
1
  {
2
2
  "name": "@kerf-js/keel",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.0",
4
+ "description": "@kerf-js/keel: KEEL generation for kerf. The `keel-lit` surface kind (surface.renderer@1) and KEEL's generative modules: trees, looks, light.",
5
+ "keywords": [
6
+ "kerf"
7
+ ],
8
+ "homepage": "https://github.com/Ravonus/kerf/tree/main/packages/keel#readme",
9
+ "bugs": {
10
+ "url": "https://github.com/Ravonus/kerf/issues"
11
+ },
12
+ "license": "MIT",
13
+ "repository": {
14
+ "type": "git",
15
+ "url": "git+https://github.com/Ravonus/kerf.git",
16
+ "directory": "packages/keel"
17
+ },
18
+ "files": [
19
+ "src",
20
+ "vendor",
21
+ "README.md",
22
+ "LICENSE"
23
+ ],
24
+ "type": "module",
25
+ "exports": {
26
+ ".": {
27
+ "types": "./src/index.d.ts",
28
+ "default": "./src/index.mjs"
29
+ },
30
+ "./runtime": "./src/runtime.ts",
31
+ "./stage": "./src/stage.ts",
32
+ "./scene": "./src/scene.ts",
33
+ "./governor": "./src/governor.ts",
34
+ "./blend": "./src/blend.ts",
35
+ "./paint": {
36
+ "types": "./src/paint.d.mts",
37
+ "default": "./src/paint.mjs"
38
+ },
39
+ "./paint-live": "./src/paint-live.ts",
40
+ "./generate": "./src/generate.ts",
41
+ "./client": {
42
+ "types": "./src/client.d.ts"
43
+ },
44
+ "./lit": {
45
+ "types": "./vendor/lit.d.mts",
46
+ "default": "./vendor/lit.mjs"
47
+ },
48
+ "./modules/*": {
49
+ "types": "./vendor/modules/*.d.mts",
50
+ "default": "./vendor/modules/*.mjs"
51
+ }
52
+ },
53
+ "publishConfig": {
54
+ "access": "public"
55
+ },
56
+ "peerDependencies": {
57
+ "@kerf-js/core": "^0.1.0"
58
+ },
59
+ "engines": {
60
+ "node": ">=24"
61
+ }
6
62
  }
@@ -0,0 +1,79 @@
1
+ // The section pass within a column: a paper panel as wide as the page's own panel, not the frame. The pass draws
2
+ // inside the column only (a scissor on the canvas; its own targets are untouched), and the frame it drew into its
3
+ // target is copied to the strips either side, so they show the scene with no panel, darkening or blur.
4
+ import type { SurfaceContext } from '@kerf-js/core/surface'
5
+ import type { LitRenderTarget } from './lit'
6
+
7
+ /** CSS px the panel keeps clear of the frame's left and right edges, or a function of the frame's CSS size. */
8
+ export type PanelInset =
9
+ | readonly [left: number, right: number]
10
+ | ((width: number, height: number) => readonly [number, number])
11
+
12
+ /** The frame as it was drawn, at its pixel: what the strips beside the column show. */
13
+ const COPY = `precision highp float;
14
+ uniform sampler2D tColor;
15
+ uniform vec2 uSize;
16
+ void main() { gl_FragColor = vec4(texture2D(tColor, gl_FragCoord.xy / uSize).rgb, 1.0); }`
17
+
18
+ /**
19
+ * Draws a pass inside the column `inset` leaves, and the frame beside it.
20
+ *
21
+ * @param vertex section-post's full-frame vertex shader.
22
+ */
23
+ export function createInset(s: SurfaceContext<'keel-lit'>, vertex: string, inset: PanelInset) {
24
+ const { lit, renderer } = s
25
+ const uniforms = { tColor: { value: null as unknown }, uSize: { value: [1, 1] } }
26
+ const material = new lit.CustomMaterial({
27
+ uniforms,
28
+ vertexShader: vertex,
29
+ fragmentShader: COPY,
30
+ depthTest: false,
31
+ depthWrite: false,
32
+ })
33
+ const quad = new lit.Mesh(lit.plane(2, 2), material)
34
+ quad.frustumCulled = false
35
+ const strips = new lit.Stage()
36
+ strips.add(quad)
37
+ const camera = new lit.OrthoCamera(-1, 1, 1, -1, 0, 1)
38
+ const clip = (x: number, width: number, height: number) => {
39
+ renderer.setScissorTest(true)
40
+ renderer.setScissor(x, 0, width, height)
41
+ }
42
+ return {
43
+ /** The column's edges this frame, CSS px from the left; null when it spans the frame. */
44
+ column(width: number, height: number): readonly [number, number] | null {
45
+ const [left, right] = typeof inset === 'function' ? inset(width, height) : inset
46
+ const from = Math.max(0, Math.round(left))
47
+ const to = Math.min(width, Math.round(width - right))
48
+ return from <= 0 && to >= width ? null : [from, Math.max(from, to)]
49
+ },
50
+ /** Runs `pass` (which draws the frame through `frame`) inside the column, then copies the frame beside it. */
51
+ draw(column: readonly [number, number], pass: (frame: () => void) => void, frame: () => void) {
52
+ const { width, height } = s.size.value
53
+ let target: LitRenderTarget | null = null
54
+ clip(column[0], column[1] - column[0], height)
55
+ pass(() => {
56
+ target = renderer.getRenderTarget()
57
+ frame()
58
+ })
59
+ if (target) {
60
+ const ratio = renderer.getPixelRatio()
61
+ uniforms.tColor.value = (target as LitRenderTarget).texture
62
+ uniforms.uSize.value = [width * ratio, height * ratio]
63
+ for (const [x, w] of [
64
+ [0, column[0]],
65
+ [column[1], width - column[1]],
66
+ ] as const) {
67
+ if (w <= 0) continue
68
+ clip(x, w, height)
69
+ renderer.render(strips, camera)
70
+ }
71
+ }
72
+ renderer.setScissorTest(false)
73
+ },
74
+ dispose() {
75
+ material.dispose()
76
+ quad.geometry.dispose()
77
+ },
78
+ }
79
+ }
package/src/blend.ts ADDED
@@ -0,0 +1,120 @@
1
+ // The stage's blend on KEEL's modules: every scene drawn through lit-finish, a hand-over through scene-blend (the less
2
+ // visible scene through a lighter finish at the levers' `blendScale`), and the active section's pass through
3
+ // section-post. `<Stage blend={keelBlend()}>`; the modules load once the stage's surface is up.
4
+ import type { SurfaceBase, SurfaceContext } from '@kerf-js/core/surface'
5
+ import { createInset, type PanelInset } from './blend-inset'
6
+ import type { BlendOptions, Levers, LiveScene, SceneBlend, ScenePost } from './scene'
7
+ import type { LitFinish } from '../vendor/modules/lit-finish.mjs'
8
+ import type { BlendSettings } from '../vendor/modules/scene-blend.mjs'
9
+ import type { PostSettings, PostValues } from '../vendor/modules/section-post.mjs'
10
+
11
+ /** Options for `keelBlend`. Each is that module's settings, checked and bounded by it. */
12
+ export interface KeelBlendOptions {
13
+ /** lit-finish's settings for the finish every scene is drawn through. */
14
+ readonly finish?: unknown
15
+ /** scene-blend's: `seed`, `lineColour`, `lines`, `glow`... `scale` comes from the levers. */
16
+ readonly blend?: Partial<Omit<BlendSettings, 'scale'>>
17
+ /** section-post's: the paper `colour`, `tear`, `fibre`, `shadow`, `grain`... */
18
+ readonly post?: Partial<PostSettings>
19
+ /**
20
+ * Keeps the panel to a column, as the page's own panel is: CSS px from the frame's left and right edges, or a
21
+ * function of the frame's CSS size, `(width) => [left, right]`. Beside the column the scene shows untouched.
22
+ */
23
+ readonly inset?: PanelInset
24
+ }
25
+
26
+ export type { PanelInset }
27
+
28
+ /** The less visible scene's finish: no ambient occlusion, bloom or TAA, which it would spend on pixels hardly seen. */
29
+ const LIGHT = { ao: 0, bloom: 0, taa: false }
30
+
31
+ /** A pass's values: a `#rrggbb` paper as display values, the rest as given. */
32
+ function valuesOf(post: ScenePost | null, hex: (value: string) => [number, number, number]) {
33
+ if (!post) return {}
34
+ const { colour, ...rest } = post
35
+ return (
36
+ colour === undefined
37
+ ? rest
38
+ : { ...rest, colour: typeof colour === 'string' ? hex(colour) : colour }
39
+ ) as PostValues
40
+ }
41
+
42
+ /** Spends the levers on the main finish: bloom as a share of its own, and TAA. */
43
+ function spender(finish: LitFinish) {
44
+ const { bloom, taa } = finish.settings
45
+ return (levers: Levers) =>
46
+ finish.setSettings({ ...finish.settings, bloom: bloom * levers.bloom, taa: taa && levers.taa })
47
+ }
48
+
49
+ /**
50
+ * The blend a `<Stage>` draws every frame with: `<Stage blend={keelBlend({ blend: { seed: 7 } })}>`. A scene alone
51
+ * goes through the finish too, so it looks the same before, during and after a hand-over.
52
+ */
53
+ export function keelBlend(options: KeelBlendOptions = {}) {
54
+ return async (surface: SurfaceBase): Promise<SceneBlend> => {
55
+ const s = surface as SurfaceContext<'keel-lit'>
56
+ const [finishing, blending, posting] = await Promise.all([
57
+ import('../vendor/modules/lit-finish.mjs'),
58
+ import('../vendor/modules/scene-blend.mjs'),
59
+ import('../vendor/modules/section-post.mjs'),
60
+ ])
61
+ const lit = s.lit as never
62
+ const renderer = s.renderer as never
63
+ const main = finishing.createLitFinish(lit, renderer, options.finish)
64
+ const scaled = finishing.createLitFinish(lit, renderer, {
65
+ ...(options.finish as object),
66
+ ...LIGHT,
67
+ })
68
+ const blend = blending.createSceneBlend(lit, renderer, { main, scaled }, options.blend)
69
+ const post = posting.createSectionPost(lit, renderer, finishing, options.post)
70
+ const inset = options.inset && createInset(s, posting.POST_VERTEX_GLSL, options.inset)
71
+ const spend = spender(main)
72
+ let sized = ''
73
+ let levers: Levers | null = null
74
+ const fit = () => {
75
+ const { width, height } = s.size.value
76
+ const ratio = s.dpr.value
77
+ const key = `${width}x${height}@${ratio}`
78
+ if (key === sized) return
79
+ sized = key
80
+ main.setSize(width, height, ratio)
81
+ blend.setSize(width, height, ratio)
82
+ post.setSize(width, height, ratio)
83
+ }
84
+ const shot = (scene: LiveScene) => scene.shot() as Parameters<typeof blend.draw>[0]
85
+ return {
86
+ draw(a: LiveScene, b: LiveScene, t: number, o: BlendOptions) {
87
+ fit()
88
+ if (o.levers !== levers) {
89
+ levers = o.levers
90
+ spend(levers)
91
+ if (blend.settings.scale !== levers.blendScale)
92
+ blend.setSettings({ ...blend.settings, scale: levers.blendScale })
93
+ }
94
+ const look = {
95
+ mode: o.mode,
96
+ pointer: o.pointer,
97
+ ...(o.centre && { centre: o.centre }),
98
+ ...(!o.lines && { lines: { in: 0, out: 0 } }),
99
+ }
100
+ const frame = () => blend.draw(shot(a), shot(b), t, look)
101
+ const values = valuesOf(o.post, posting.displayColour)
102
+ const { width, height } = s.size.value
103
+ // A column only while the panel shows: a frame with no panel draws straight to the canvas, whole.
104
+ const column =
105
+ inset && posting.panelShows(posting.frameOf(values, post.settings))
106
+ ? inset.column(width, height)
107
+ : null
108
+ if (column) inset!.draw(column, (drawn) => post.render(drawn, values), frame)
109
+ else post.render(frame, values)
110
+ },
111
+ dispose() {
112
+ blend.dispose()
113
+ post.dispose()
114
+ inset?.dispose()
115
+ main.dispose()
116
+ scaled.dispose()
117
+ },
118
+ }
119
+ }
120
+ }
@@ -0,0 +1,9 @@
1
+ // Ambient types for `?paint` imports: add `"types": ["@kerf-js/keel/client"]` to tsconfig.
2
+
3
+ /** `./card.paint.json?paint`: a surface painted at build, as `@kerf-js/core/media`'s record. */
4
+ declare module '*?paint' {
5
+ import type { MediaAsset } from '@kerf-js/core/media'
6
+ const asset: MediaAsset
7
+ /** The painted image's record: its AVIF ladder and placeholder with `media()`, the PNG alone without. */
8
+ export default asset
9
+ }
@@ -0,0 +1,24 @@
1
+ // The portrait's bust, its parts meshed: the slow half of a portrait (a few hundred ms at `hero`). From the sitter's
2
+ // settings, so a page can ask before it has loaded the module, or from a recipe.
3
+ import {
4
+ buildBust,
5
+ digestOf,
6
+ portraitSettings,
7
+ sitterOf,
8
+ type Bust,
9
+ type BustRecipe,
10
+ type Palette,
11
+ type PortraitSettings,
12
+ } from '../../vendor/modules/portrait.mjs'
13
+
14
+ /** A recipe, or the settings `sitterOf` makes one from (`{ seed: 7, face: 'A', detail: 'hero' }`). */
15
+ export type BustJob = BustRecipe | Partial<PortraitSettings>
16
+
17
+ /** A bust, the digest of its recipe, and the palette when it came from settings. */
18
+ export type BustResult = Bust & { readonly digest: string; readonly palette?: Palette }
19
+
20
+ export function run(job: BustJob): BustResult {
21
+ if (typeof job.detail === 'object') return { ...buildBust(job), digest: digestOf(job) }
22
+ const { recipe, palette } = sitterOf(portraitSettings(job))
23
+ return { ...buildBust(recipe), digest: digestOf(recipe), palette }
24
+ }
@@ -0,0 +1,4 @@
1
+ import { run } from './bust'
2
+ import { serve } from './serve'
3
+
4
+ serve(run)