@kerf-js/keel-pixel 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.
- package/LICENSE +16 -0
- package/README.md +317 -2
- package/package.json +43 -3
- package/src/index.d.ts +21 -0
- package/src/index.mjs +35 -0
- package/src/runtime.mjs +15 -0
- package/src/theme.mjs +1 -0
- package/src/vendor-types.d.ts +24 -0
- package/vendor/LICENSE +21 -0
- package/vendor/README.md +11 -0
- package/vendor/keel-render/core-primitives.mjs +478 -0
- package/vendor/keel-render/effects-world.mjs +439 -0
- package/vendor/keel-render/indexed-render.mjs +516 -0
- package/vendor/keel-render/pixel-raster.mjs +512 -0
- package/vendor/keel-render/render-passes.mjs +530 -0
- package/vendor/keel-render/renderer-api.mjs +121 -0
- package/vendor/keel-render.mjs +1 -0
- package/vendor/keel-styles.css +7 -0
- package/vendor/keel-theme/codec-runtime.mjs +549 -0
- package/vendor/keel-theme/collection-codecs.mjs +360 -0
- package/vendor/keel-theme/color-font.mjs +471 -0
- package/vendor/keel-theme/glyph-theme.mjs +529 -0
- package/vendor/keel-theme/icon-schema.mjs +540 -0
- package/vendor/keel-theme/scalar-codecs.mjs +535 -0
- package/vendor/keel-theme/schema-codec.mjs +515 -0
- package/vendor/keel-theme/schema-theme.mjs +533 -0
- package/vendor/keel-theme.mjs +1 -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,318 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://github.com/Ravonus/kerf">
|
|
3
|
+
<img src="https://raw.githubusercontent.com/Ravonus/kerf/main/site/public/logo.svg" width="88" height="88" alt="Kerf">
|
|
4
|
+
</a>
|
|
5
|
+
</p>
|
|
2
6
|
|
|
3
|
-
|
|
7
|
+
<h1 align="center">@kerf-js/keel-pixel</h1>
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
<strong>KEEL's WebGL2 pixel renderer as a Kerf surface kind: <code>kind: 'keel-pixel'</code>.</strong><br>
|
|
11
|
+
A fixed low-resolution target scaled up with nearest sampling, plus KEEL's seeded theme recipes as palettes and CSS variables.
|
|
12
|
+
</p>
|
|
13
|
+
|
|
14
|
+
<p align="center">
|
|
15
|
+
<a href="https://www.npmjs.com/package/@kerf-js/keel-pixel"><img src="https://img.shields.io/npm/v/@kerf-js/keel-pixel?color=145c3c&label=npm" alt="npm version"></a>
|
|
16
|
+
<a href="https://github.com/Ravonus/kerf/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-145c3c" alt="MIT license"></a>
|
|
17
|
+
<a href="https://github.com/Ravonus/kerf/actions"><img src="https://img.shields.io/github/actions/workflow/status/Ravonus/kerf/quality.yml?branch=main&label=checks" alt="checks"></a>
|
|
18
|
+
</p>
|
|
19
|
+
|
|
20
|
+
<p align="center">
|
|
21
|
+
<a href="#quick-start">Quick start</a> ·
|
|
22
|
+
<a href="https://github.com/Ravonus/kerf/tree/main/docs">Docs</a> ·
|
|
23
|
+
<a href="https://github.com/Ravonus/kerf/tree/main/examples">Examples</a> ·
|
|
24
|
+
<a href="https://github.com/Ravonus/kerf/blob/main/CHANGELOG.md">Changelog</a> ·
|
|
25
|
+
<a href="https://github.com/Ravonus/kerf">GitHub</a>
|
|
26
|
+
</p>
|
|
27
|
+
|
|
28
|
+
> [!IMPORTANT]
|
|
29
|
+
> **Early release (0.1.x).** APIs can change between minor versions. Pin the version and read the
|
|
30
|
+
> [changelog](https://github.com/Ravonus/kerf/blob/main/CHANGELOG.md) before you upgrade.
|
|
31
|
+
|
|
32
|
+
Kerf's surfaces (`@kerf-js/core/surface`) are canvas or WebGL views that sit in layout like any other child: `setup`
|
|
33
|
+
runs once on the client, props stay live, and nothing around them re-renders. Core has two built-in kinds, `canvas2d`
|
|
34
|
+
and `webgl2`. This plugin adds a third, `keel-pixel`, through the `surface.renderer@1` slot. A `keel-pixel` surface gets
|
|
35
|
+
`s.px`, KEEL's `PixelRenderer`, which owns the GL context and draws a palette-indexed 3D world into a small fixed
|
|
36
|
+
target. It also exports KEEL's theme recipes, which turn a seed into palette ramps and `--keel-*` CSS variables.
|
|
37
|
+
|
|
38
|
+
The renderer and theme code are vendored from KEEL's engine (keel-engine) at a pinned commit; see
|
|
39
|
+
[Vendored code](#vendored-code).
|
|
40
|
+
|
|
41
|
+
## Highlights
|
|
42
|
+
|
|
43
|
+
- **A new surface kind, nothing else to wire.** `keelPixel()` in `plugins` registers `keel-pixel`; `defineSurface({ kind:
|
|
44
|
+
'keel-pixel', pixel: { width, height } })` uses it.
|
|
45
|
+
- **Loaded only where it's used.** The renderer sits behind the slot's `import()`, so only pages that mount a
|
|
46
|
+
`keel-pixel` surface download it.
|
|
47
|
+
- **Fixed pixel target.** `pixel: { width, height }` renders at that resolution and scales up by an integer with nearest
|
|
48
|
+
sampling.
|
|
49
|
+
- **Seeded themes.** `recipeTheme({ seed, culture })` gives the same theme every time for the same recipe: palette ramps,
|
|
50
|
+
frame, type, spacing and motion. `themeTokens(theme, scale)` turns it into CSS variables.
|
|
51
|
+
- **KEEL's UI styles.** `@kerf-js/keel-pixel/styles.css` styles `[data-keel-theme]`, `.keel-panel` and
|
|
52
|
+
`.keel-button` from those variables, and drops animation under `prefers-reduced-motion`.
|
|
53
|
+
- **Typed `s.px`.** The package augments `@kerf-js/core/surface`'s `SurfaceKinds`, so `s.px` is typed inside `setup`.
|
|
54
|
+
- **Clean teardown.** When the surface goes, the WebGL context is released with `WEBGL_lose_context`.
|
|
55
|
+
|
|
56
|
+
## Install
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
# npm
|
|
60
|
+
npm install @kerf-js/keel-pixel
|
|
61
|
+
|
|
62
|
+
# pnpm
|
|
63
|
+
pnpm add @kerf-js/keel-pixel
|
|
64
|
+
|
|
65
|
+
# bun
|
|
66
|
+
bun add @kerf-js/keel-pixel
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Or let the `kerf` CLI install it and add it to `kerf.config.ts` in one step:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
npx kerf add surface-keel
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
The
|
|
76
|
+
package has no `/plugin` entry and no default export, so `kerf add` writes `import { keelPixel } from
|
|
77
|
+
'@kerf-js/keel-pixel'` and adds `keelPixel()` to `plugins`.
|
|
78
|
+
|
|
79
|
+
**What it needs:** a browser with WebGL2. There's no server or build-time dependency. If you draw canvas text with
|
|
80
|
+
`s.text()` on a surface, add `text()` from `@kerf-js/text` too (the `text.measure` slot), as the demo does.
|
|
81
|
+
|
|
82
|
+
## Quick start
|
|
83
|
+
|
|
84
|
+
```ts
|
|
85
|
+
// kerf.config.ts
|
|
86
|
+
import { defineConfig } from '@kerf-js/core/config'
|
|
87
|
+
import { text } from '@kerf-js/text'
|
|
88
|
+
import { keelPixel } from '@kerf-js/keel-pixel'
|
|
89
|
+
|
|
90
|
+
export default defineConfig({ plugins: [text(), keelPixel()] })
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
```tsx
|
|
94
|
+
// src/routes/scene.tsx
|
|
95
|
+
import { defineSurface, Surface } from '@kerf-js/core/surface'
|
|
96
|
+
import {
|
|
97
|
+
recipeTheme,
|
|
98
|
+
themeTokens,
|
|
99
|
+
} from '@kerf-js/keel-pixel/theme'
|
|
100
|
+
import '@kerf-js/keel-pixel/styles.css'
|
|
101
|
+
|
|
102
|
+
const theme = recipeTheme({
|
|
103
|
+
seed: 'keel/react-demo',
|
|
104
|
+
culture: 'clean',
|
|
105
|
+
})
|
|
106
|
+
const css = Object.entries(themeTokens(theme, 2))
|
|
107
|
+
.map(([k, v]) => `${k}:${v}`)
|
|
108
|
+
.join(';')
|
|
109
|
+
|
|
110
|
+
// Palette ramps are packed RGB numbers; the renderer takes [r, g, b]
|
|
111
|
+
// triples and named ranges.
|
|
112
|
+
const colours = [
|
|
113
|
+
...theme.palette.surface,
|
|
114
|
+
...theme.palette.accent,
|
|
115
|
+
].map((c: number) => [c & 255, (c >>> 8) & 255, (c >>> 16) & 255])
|
|
116
|
+
const ramps = {
|
|
117
|
+
surface: [0, theme.palette.surface.length],
|
|
118
|
+
accent: [theme.palette.surface.length, theme.palette.accent.length],
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
export const Scene = defineSurface({
|
|
122
|
+
name: 'keel-scene',
|
|
123
|
+
kind: 'keel-pixel',
|
|
124
|
+
pixel: { width: 256, height: 144 },
|
|
125
|
+
fps: 30,
|
|
126
|
+
setup(s) {
|
|
127
|
+
s.px.setPalette(colours, ramps)
|
|
128
|
+
s.px.setMaterials([{ ramp: 'surface' }, { ramp: 'accent' }])
|
|
129
|
+
s.px.setWorld({
|
|
130
|
+
boxes: [
|
|
131
|
+
{ c: [0, -0.5, 0], h: [5, 0.5, 5], mat: 0 },
|
|
132
|
+
{ c: [0, 1, 0], h: [0.75, 1, 0.75], mat: 1 },
|
|
133
|
+
],
|
|
134
|
+
})
|
|
135
|
+
s.px.setStyle({ screen: 4 })
|
|
136
|
+
s.frame((t) =>
|
|
137
|
+
s.px.render({
|
|
138
|
+
eye: [Math.sin(t.seconds) * 5, 3, Math.cos(t.seconds) * 5],
|
|
139
|
+
target: [0, 1, 0],
|
|
140
|
+
time: t.seconds,
|
|
141
|
+
}),
|
|
142
|
+
)
|
|
143
|
+
},
|
|
144
|
+
})
|
|
145
|
+
|
|
146
|
+
export default function Page() {
|
|
147
|
+
return (
|
|
148
|
+
<div
|
|
149
|
+
data-keel-theme={theme.key}
|
|
150
|
+
style={css}
|
|
151
|
+
>
|
|
152
|
+
<Surface
|
|
153
|
+
use={Scene}
|
|
154
|
+
label="A box on a floor, orbited by the camera"
|
|
155
|
+
style="max-width:640px"
|
|
156
|
+
/>
|
|
157
|
+
</div>
|
|
158
|
+
)
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
This is the package's own demo (`demo/KeelDemo.tsx`, a port of keel-engine's React scaffold demo), trimmed. The camera
|
|
163
|
+
orbits on the shared surface clock, so `clock.pause()` from `@kerf-js/core/surface` stops it, and under
|
|
164
|
+
`prefers-reduced-motion: reduce` it starts paused.
|
|
165
|
+
|
|
166
|
+
## How it plugs into Kerf
|
|
167
|
+
|
|
168
|
+
| Piece | Detail |
|
|
169
|
+
| --- | --- |
|
|
170
|
+
| Slot | `surface.renderer@1`, keyed, client side only. This plugin provides the key `keel-pixel`. |
|
|
171
|
+
| Provider | `renderer` from `@kerf-js/keel-pixel/runtime`. Its `context(canvas, def)` creates the `PixelRenderer` and returns `{ fields: { px }, dispose }`. |
|
|
172
|
+
| Loading | Core's surface mount handles `canvas2d` and `webgl2` itself; any other kind is loaded through `import('kerf:slot/surface.renderer')`. If loading fails, the error is logged and the host element gets `data-surface-error="keel-pixel"`. |
|
|
173
|
+
| Namespace | `surface-keel/`. |
|
|
174
|
+
| Agent notes | `kind: 'keel-pixel'` needs `pixel: { width, height }`; `s.px` is KEEL's `PixelRenderer`; palettes come from `recipeTheme()`. |
|
|
175
|
+
|
|
176
|
+
Everything else about a surface is core's: `<Surface>` takes `use`, your props, `aspect` (default `2/1`), `label`
|
|
177
|
+
(required) or `decorative`, `class` and `style`, and the server renders a sized placeholder so nothing shifts when the
|
|
178
|
+
canvas mounts. `kerf docs surface` covers it.
|
|
179
|
+
|
|
180
|
+
## `defineSurface` with `kind: 'keel-pixel'`
|
|
181
|
+
|
|
182
|
+
| Field | Type | Default | What it does |
|
|
183
|
+
| --- | --- | --- | --- |
|
|
184
|
+
| `kind` | `'keel-pixel'` | | Selects this renderer. |
|
|
185
|
+
| `pixel` | `{ width: number, height: number }` | required | The fixed render target. Without it, mounting throws ``surface `<name>`: `keel-pixel` needs `pixel: { width, height }` ``. |
|
|
186
|
+
| `fps` | `number` | `60` | Core's frame cap for `s.frame`. |
|
|
187
|
+
| `setup(s, props)` | function | | Runs once on the client. `s.px` is the renderer; `s.frame`, `s.draw`, `s.size`, `s.el` and `s.text` work as for any surface. |
|
|
188
|
+
|
|
189
|
+
### `s.px`: the renderer
|
|
190
|
+
|
|
191
|
+
The typed part of KEEL's `PixelRenderer` (`src/vendor-types.d.ts`). The rest of the vendored API is reachable but
|
|
192
|
+
untyped.
|
|
193
|
+
|
|
194
|
+
| Method | What it takes |
|
|
195
|
+
| --- | --- |
|
|
196
|
+
| `setPalette(colours, ramps)` | `colours`: `[r, g, b]` triples. `ramps`: named `[start, length]` ranges into `colours`. |
|
|
197
|
+
| `setMaterials(materials)` | `{ ramp: string }[]`: material `i` shades from the named ramp. |
|
|
198
|
+
| `setWorld(world)` | The scene, for example `{ boxes: [{ c, h, mat }] }` (centre, half-extents, material index). |
|
|
199
|
+
| `setStyle(style)` | Render style, for example `{ screen: 4 }`. |
|
|
200
|
+
| `render(view)` | One frame: `{ eye, target, time }`. Call it from `s.frame`. |
|
|
201
|
+
|
|
202
|
+
## Themes
|
|
203
|
+
|
|
204
|
+
```ts
|
|
205
|
+
import {
|
|
206
|
+
recipeTheme,
|
|
207
|
+
themeTokens,
|
|
208
|
+
} from '@kerf-js/keel-pixel/theme'
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
| Function | Signature | What it returns |
|
|
212
|
+
| --- | --- | --- |
|
|
213
|
+
| `recipeTheme(recipe?)` | `{ seed?, culture?, pins? }` | A theme: `key`, `palette`, and frame, type, spacing and motion. The same recipe gives the same theme. |
|
|
214
|
+
| `themeTokens(theme, scale?)` | theme, integer scale | `--keel-*` CSS variables at that scale; at scale 2, `--keel-px` is `2px`. |
|
|
215
|
+
|
|
216
|
+
`palette` (type `Palette`) has `tone`, ramps `surface`, `ink`, `accent`, `good`, `warn`, `bad` (packed RGB numbers),
|
|
217
|
+
`team`, `outline`, `onAccent`, and `hues: { surface, accent }`.
|
|
218
|
+
|
|
219
|
+
`styles.css` reads `--keel-font`, `--keel-body`, `--keel-ink`, `--keel-surface`, `--keel-border`, `--keel-outline`,
|
|
220
|
+
`--keel-pad`, `--keel-on-accent`, `--keel-accent` and `--keel-px`, and sets `image-rendering: pixelated` on canvases inside
|
|
221
|
+
`.keel-canvas`.
|
|
222
|
+
|
|
223
|
+
## API reference
|
|
224
|
+
|
|
225
|
+
| Export | Entry | What it is |
|
|
226
|
+
| --- | --- | --- |
|
|
227
|
+
| `keelPixel()` | `@kerf-js/keel-pixel` | The plugin for `kerf.config.ts`. |
|
|
228
|
+
| `recipeTheme`, `themeTokens` | `@kerf-js/keel-pixel/theme` | KEEL's theme recipes (types come from the main entry's declarations). |
|
|
229
|
+
| `renderer` | `@kerf-js/keel-pixel/runtime` | The `surface.renderer@1` provider. Loaded by the slot; you don't import it yourself. |
|
|
230
|
+
| `styles.css` | `@kerf-js/keel-pixel/styles.css` | KEEL's UI styles, driven by the theme's CSS variables. |
|
|
231
|
+
| `SurfaceKinds['keel-pixel']` | type augmentation of `@kerf-js/core/surface` | Makes `s.px` a `PixelRenderer` in `setup`. |
|
|
232
|
+
|
|
233
|
+
## Recipes
|
|
234
|
+
|
|
235
|
+
**A play/pause button beside the scene.** The clock is shared, and `clock.playing` is a box the button reads:
|
|
236
|
+
|
|
237
|
+
```tsx
|
|
238
|
+
import { clock } from '@kerf-js/core/surface'
|
|
239
|
+
|
|
240
|
+
export function Controls() {
|
|
241
|
+
return (
|
|
242
|
+
<section
|
|
243
|
+
class="keel-panel"
|
|
244
|
+
aria-label="Scene controls"
|
|
245
|
+
>
|
|
246
|
+
<button
|
|
247
|
+
class="keel-button"
|
|
248
|
+
type="button"
|
|
249
|
+
onClick={() =>
|
|
250
|
+
clock.playing.value ? clock.pause() : clock.play()
|
|
251
|
+
}
|
|
252
|
+
>
|
|
253
|
+
{clock.playing.value ? 'PAUSE' : 'PLAY'}
|
|
254
|
+
</button>
|
|
255
|
+
</section>
|
|
256
|
+
)
|
|
257
|
+
}
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
**A deterministic frame for a screenshot.** `clock.seek(seconds)` paints every animated surface at that time.
|
|
261
|
+
|
|
262
|
+
## Limits
|
|
263
|
+
|
|
264
|
+
- Client only, and WebGL2 only. The server renders the sized placeholder.
|
|
265
|
+
- `pixel` is required: there is no resolution-following mode for this kind.
|
|
266
|
+
- Only the five `PixelRenderer` methods above are typed.
|
|
267
|
+
- The vendored engine is a snapshot. New KEEL features arrive only when the vendor files are regenerated from a newer
|
|
268
|
+
pin.
|
|
269
|
+
|
|
270
|
+
## Troubleshooting
|
|
271
|
+
|
|
272
|
+
| Symptom | Cause and fix |
|
|
273
|
+
| --- | --- |
|
|
274
|
+
| The surface stays a placeholder and has `data-surface-error="keel-pixel"` | The renderer failed to load or set up; the browser console has the error. Check that `keelPixel()` is in `plugins`, and that the browser has WebGL2. |
|
|
275
|
+
| ``surface `<name>`: `keel-pixel` needs `pixel: { width, height }` `` | Add `pixel` to the definition. |
|
|
276
|
+
| P101 for `text.measure` | `s.text()` on a canvas surface needs `text()` from `@kerf-js/text` in `plugins`. |
|
|
277
|
+
| Blurry pixels | Put the canvas inside `.keel-canvas` and import `styles.css`, or set `image-rendering: pixelated` yourself. |
|
|
278
|
+
|
|
279
|
+
## Vendored code
|
|
280
|
+
|
|
281
|
+
`vendor/` is generated by `scripts/vendor.mjs` from keel-engine commit `4bcccc7` and must not be edited by hand:
|
|
282
|
+
|
|
283
|
+
| File | From keel-engine |
|
|
284
|
+
| --- | --- |
|
|
285
|
+
| `keel-render.mjs` (and `keel-render/`) | `createPixelRenderer` from `packages/render` |
|
|
286
|
+
| `keel-theme.mjs` (and `keel-theme/`) | `recipeTheme` and `themeTokens` from `packages/react/src/design.ts` |
|
|
287
|
+
| `keel-styles.css` | `packages/react/src/styles.css` |
|
|
288
|
+
|
|
289
|
+
The checked patches in `scripts/vendor/` move the pinned bundles into local modules. `pnpm --filter
|
|
290
|
+
@kerf-js/keel-pixel vendor` regenerates them from a keel-engine checkout: `~/dev/keel-engine`, or a path
|
|
291
|
+
passed as its argument. It refuses a source without the pinned commit. The test that regenerates them reads
|
|
292
|
+
`KEEL_ENGINE`, and skips without a checkout.
|
|
293
|
+
|
|
294
|
+
## Related packages
|
|
295
|
+
|
|
296
|
+
| Package | What it is |
|
|
297
|
+
| --- | --- |
|
|
298
|
+
| [`@kerf-js/core`](https://www.npmjs.com/package/@kerf-js/core) | `defineSurface`, `<Surface>` and the clock (`@kerf-js/core/surface`). |
|
|
299
|
+
| [`@kerf-js/text`](https://www.npmjs.com/package/@kerf-js/text) | The `text.measure` slot that `s.text()` on a canvas needs. |
|
|
300
|
+
| [`@kerf-js/cli`](https://www.npmjs.com/package/@kerf-js/cli) | `kerf add surface-keel`, `kerf docs surface`, `kerf surfaces --json`. |
|
|
301
|
+
|
|
302
|
+
## Contributing
|
|
303
|
+
|
|
304
|
+
See [CONTRIBUTING.md](https://github.com/Ravonus/kerf/blob/main/CONTRIBUTING.md). From the repository root:
|
|
305
|
+
|
|
306
|
+
```bash
|
|
307
|
+
# Plugin contract, themes, vendor checks
|
|
308
|
+
pnpm --filter @kerf-js/keel-pixel test
|
|
309
|
+
# Builds demo/ and checks pixels in Chrome and WebKit
|
|
310
|
+
pnpm --filter @kerf-js/keel-pixel test:e2e
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
The end-to-end run builds `demo/` with `@kerf-js/core/vite` and needs `@kerf-js/text` built first.
|
|
314
|
+
|
|
315
|
+
## License
|
|
316
|
+
|
|
317
|
+
[MIT](https://github.com/Ravonus/kerf/blob/main/LICENSE). The vendored KEEL code is MIT too; its licence is kept
|
|
318
|
+
byte-for-byte in [`vendor/LICENSE`](https://github.com/Ravonus/kerf/blob/main/packages/keel-pixel/vendor/LICENSE).
|
package/package.json
CHANGED
|
@@ -1,6 +1,46 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kerf-js/keel-pixel",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "@kerf-js/keel-pixel: the `keel-pixel` surface kind (surface.renderer@1): KEEL's WebGL2 pixel renderer and theme recipes.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/Ravonus/kerf.git",
|
|
9
|
+
"directory": "packages/keel-pixel"
|
|
10
|
+
},
|
|
11
|
+
"homepage": "https://github.com/Ravonus/kerf/tree/main/packages/keel-pixel#readme",
|
|
12
|
+
"bugs": {
|
|
13
|
+
"url": "https://github.com/Ravonus/kerf/issues"
|
|
14
|
+
},
|
|
15
|
+
"type": "module",
|
|
16
|
+
"exports": {
|
|
17
|
+
".": {
|
|
18
|
+
"types": "./src/index.d.ts",
|
|
19
|
+
"default": "./src/index.mjs"
|
|
20
|
+
},
|
|
21
|
+
"./runtime": "./src/runtime.mjs",
|
|
22
|
+
"./theme": {
|
|
23
|
+
"types": "./src/index.d.ts",
|
|
24
|
+
"default": "./src/theme.mjs"
|
|
25
|
+
},
|
|
26
|
+
"./styles.css": "./vendor/keel-styles.css"
|
|
27
|
+
},
|
|
28
|
+
"peerDependencies": {
|
|
29
|
+
"@kerf-js/core": "^0.1.0"
|
|
30
|
+
},
|
|
31
|
+
"engines": {
|
|
32
|
+
"node": ">=24"
|
|
33
|
+
},
|
|
34
|
+
"keywords": [
|
|
35
|
+
"kerf"
|
|
36
|
+
],
|
|
37
|
+
"files": [
|
|
38
|
+
"src",
|
|
39
|
+
"vendor",
|
|
40
|
+
"README.md",
|
|
41
|
+
"LICENSE"
|
|
42
|
+
],
|
|
43
|
+
"publishConfig": {
|
|
44
|
+
"access": "public"
|
|
45
|
+
}
|
|
6
46
|
}
|
package/src/index.d.ts
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import type { PluginEntry } from '@kerf-js/core/config'
|
|
2
|
+
import type { Palette, PixelRenderer } from './vendor-types'
|
|
3
|
+
|
|
4
|
+
/** The plugin for `kerf.config.ts`: adds the `keel-pixel` surface kind and KEEL's theme. */
|
|
5
|
+
export declare const keelPixel: () => PluginEntry
|
|
6
|
+
|
|
7
|
+
/** `{ seed, culture, pins }` → KEEL's theme: palette ramps, frame, type, spacing and motion. */
|
|
8
|
+
export declare function recipeTheme(recipe?: {
|
|
9
|
+
seed?: string
|
|
10
|
+
culture?: string
|
|
11
|
+
pins?: Record<string, unknown>
|
|
12
|
+
}): { key: string; palette: Palette; [k: string]: unknown }
|
|
13
|
+
/** A theme as `--keel-*` CSS variables at an integer scale. */
|
|
14
|
+
export declare function themeTokens(theme: unknown, scale?: number): Record<string, string>
|
|
15
|
+
|
|
16
|
+
declare module '@kerf-js/core/surface' {
|
|
17
|
+
interface SurfaceKinds {
|
|
18
|
+
/** `s.px`: KEEL's PixelRenderer. */
|
|
19
|
+
'keel-pixel': { px: PixelRenderer }
|
|
20
|
+
}
|
|
21
|
+
}
|
package/src/index.mjs
ADDED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
// KEEL's renderer stays behind the slot's `import()` so only pages that mount it load it.
|
|
2
|
+
import { definePlugin, defineSlot, provide } from '@kerf-js/core/plugin'
|
|
3
|
+
|
|
4
|
+
const renderer = defineSlot({
|
|
5
|
+
id: 'surface.renderer',
|
|
6
|
+
version: 1,
|
|
7
|
+
cardinality: 'keyed',
|
|
8
|
+
sides: ['client'],
|
|
9
|
+
})
|
|
10
|
+
|
|
11
|
+
export const keelPixel = definePlugin({
|
|
12
|
+
name: '@kerf-js/keel-pixel',
|
|
13
|
+
version: '0.1.0',
|
|
14
|
+
kerf: '*',
|
|
15
|
+
namespace: 'surface-keel/',
|
|
16
|
+
contribute: () => ({
|
|
17
|
+
provides: [
|
|
18
|
+
provide(renderer, {
|
|
19
|
+
key: 'keel-pixel',
|
|
20
|
+
sides: { client: { module: '@kerf-js/keel-pixel/runtime', export: 'renderer' } },
|
|
21
|
+
}),
|
|
22
|
+
],
|
|
23
|
+
agents: {
|
|
24
|
+
title: 'KEEL surfaces (@kerf-js/keel-pixel)',
|
|
25
|
+
text: "- `kind: 'keel-pixel'` needs `pixel: { width, height }`. `s.px` is KEEL's `PixelRenderer`: `setPalette`, `setMaterials`, `setWorld`, `render`. Palettes come from `recipeTheme()` in `@kerf-js/keel-pixel/theme`.",
|
|
26
|
+
},
|
|
27
|
+
catalog: [
|
|
28
|
+
{
|
|
29
|
+
name: 'keelPixel',
|
|
30
|
+
import: '@kerf-js/keel-pixel',
|
|
31
|
+
summary: 'surface.renderer: keel-pixel',
|
|
32
|
+
},
|
|
33
|
+
],
|
|
34
|
+
}),
|
|
35
|
+
})
|
package/src/runtime.mjs
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
// surface.renderer@1 for `keel-pixel`. The renderer owns the GL context, so a surface adds only the fixed target.
|
|
2
|
+
import { createPixelRenderer } from '../vendor/keel-render.mjs'
|
|
3
|
+
|
|
4
|
+
/** The surface.renderer@1 provider: `context` makes the surface's `s.px` and undoes it when the surface goes. */
|
|
5
|
+
export const renderer = {
|
|
6
|
+
context(canvas, def) {
|
|
7
|
+
if (!def.pixel)
|
|
8
|
+
throw new Error(`surface \`${def.name}\`: \`keel-pixel\` needs \`pixel: { width, height }\``)
|
|
9
|
+
const px = createPixelRenderer(canvas, def.pixel)
|
|
10
|
+
return {
|
|
11
|
+
fields: { px },
|
|
12
|
+
dispose: () => canvas.getContext('webgl2')?.getExtension('WEBGL_lose_context')?.loseContext(),
|
|
13
|
+
}
|
|
14
|
+
},
|
|
15
|
+
}
|
package/src/theme.mjs
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { recipeTheme, themeTokens } from '../vendor/keel-theme.mjs'
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
/** A KEEL theme's colours: ramps of packed RGB, as the vendored engine computes them. */
|
|
2
|
+
export interface Palette {
|
|
3
|
+
tone: string
|
|
4
|
+
surface: number[]
|
|
5
|
+
ink: number[]
|
|
6
|
+
accent: number[]
|
|
7
|
+
good: number[]
|
|
8
|
+
warn: number[]
|
|
9
|
+
bad: number[]
|
|
10
|
+
team: unknown[]
|
|
11
|
+
outline: number
|
|
12
|
+
onAccent: number
|
|
13
|
+
hues: { surface: number; accent: number }
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/** KEEL's renderer, typed as far as a surface drives one. The rest of the vendored API is reachable, untyped. */
|
|
17
|
+
export interface PixelRenderer {
|
|
18
|
+
setPalette(colours: number[][], ramps: Record<string, number[]>): void
|
|
19
|
+
setMaterials(materials: { ramp: string }[]): void
|
|
20
|
+
setWorld(world: object): void
|
|
21
|
+
setStyle(style: object): void
|
|
22
|
+
render(view: object): void
|
|
23
|
+
[other: string]: unknown
|
|
24
|
+
}
|
package/vendor/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 ravonus
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/vendor/README.md
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# vendor
|
|
2
|
+
|
|
3
|
+
Built by `scripts/vendor.mjs` from keel-engine 4bcccc7 (MIT; see LICENSE).
|
|
4
|
+
The checked patches move the pinned bundles into local modules. Don't edit generated modules directly.
|
|
5
|
+
|
|
6
|
+
The existing LICENSE is preserved byte-for-byte. At the pinned commit, upstream's LICENSE names
|
|
7
|
+
Chad Koslovsky and contributors; the preserved vendored copy names ravonus.
|
|
8
|
+
|
|
9
|
+
- `keel-render.mjs`: `createPixelRenderer` from `packages/render` and its local modules.
|
|
10
|
+
- `keel-theme.mjs`: `recipeTheme` and `themeTokens` from `packages/react/src/design.ts` and their local modules.
|
|
11
|
+
- `keel-styles.css`: `packages/react/src/styles.css`.
|