@weft-js/plugin-surface-keel 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,16 @@
+MIT License
+
+Copyright (c) 2026 ravonus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @weft-js/plugin-surface-keel
 
-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.
+> **Early release (0.1.0).** APIs will change between minor versions.
+
+The `keel-pixel` surface kind (surface.renderer@1): KEEL's WebGL2 pixel renderer and theme recipes..
+
+```bash
+npm install @weft-js/plugin-surface-keel
+```

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@weft-js/plugin-surface-keel",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "@weft-js/plugin-surface-keel: the `keel-pixel` surface kind (surface.renderer@1): KEEL's WebGL2 pixel renderer and theme recipes.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.mjs"
+    },
+    "./runtime": "./src/runtime.mjs",
+    "./theme": {
+      "types": "./src/index.d.ts",
+      "default": "./src/theme.mjs"
+    },
+    "./styles.css": "./vendor/keel-styles.css"
+  },
+  "peerDependencies": {
+    "@weft-js/core": "^0.1.0"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "keywords": [
+    "weft"
+  ],
+  "files": [
+    "src",
+    "vendor",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,17 @@
+import type { PluginEntry } from '@weft-js/core/config'
+import type { Palette, PixelRenderer } from './vendor-types'
+
+/** The plugin for `weft.config.ts`: adds the `keel-pixel` surface kind and KEEL's theme. */
+export declare const keel: () => PluginEntry
+
+/** `{ seed, culture, pins }` → KEEL's theme: palette ramps, frame, type, spacing and motion. */
+export declare function recipeTheme(recipe?: { seed?: string; culture?: string; pins?: Record<string, unknown> }): { key: string; palette: Palette; [k: string]: unknown }
+/** A theme as `--keel-*` CSS variables at an integer scale. */
+export declare function themeTokens(theme: unknown, scale?: number): Record<string, string>
+
+declare module '@weft-js/core/surface' {
+  interface SurfaceKinds {
+    /** `s.px`: KEEL's PixelRenderer. */
+    'keel-pixel': { px: PixelRenderer }
+  }
+}

package/src/index.mjs

@@ -0,0 +1,20 @@
+// keel() for weft.config.ts (PLAN §5, research 33 §5): the `keel-pixel` surface kind. KEEL's renderer is ~27 KB br, so it
+// stays behind the slot's `import()` and only pages that mount a `keel-pixel` surface load it.
+import { definePlugin, defineSlot, provide } from '@weft-js/core/plugin'
+
+const renderer = defineSlot({ id: 'surface.renderer', version: 1, cardinality: 'keyed', sides: ['client'] })
+
+export const keel = definePlugin({
+  name: '@weft-js/plugin-surface-keel',
+  version: '0.1.0',
+  weft: '*',
+  namespace: 'surface-keel/',
+  contribute: () => ({
+    provides: [provide(renderer, { key: 'keel-pixel', sides: { client: { module: '@weft-js/plugin-surface-keel/runtime', export: 'renderer' } } })],
+    agents: {
+      title: 'KEEL surfaces (@weft-js/plugin-surface-keel)',
+      text: "- `kind: 'keel-pixel'` needs `pixel: { width, height }`. `s.px` is KEEL's `PixelRenderer`: `setPalette`, `setMaterials`, `setWorld`, `render`. Palettes come from `recipeTheme()` in `@weft-js/plugin-surface-keel/theme`.",
+    },
+    catalog: [{ name: 'keel', import: '@weft-js/plugin-surface-keel', summary: 'surface.renderer: keel-pixel' }],
+  }),
+})

package/src/runtime.mjs

@@ -0,0 +1,11 @@
+// surface.renderer@1 for `keel-pixel`. The renderer owns the GL context, so a surface adds only the fixed target.
+import { createPixelRenderer } from '../vendor/keel-render.mjs'
+
+/** The surface.renderer@1 provider: `context` makes the surface's `s.px` and undoes it when the surface goes. */
+export const renderer = {
+  context(canvas, def) {
+    if (!def.pixel) throw new Error(`surface \`${def.name}\`: \`keel-pixel\` needs \`pixel: { width, height }\``)
+    const px = createPixelRenderer(canvas, def.pixel)
+    return { fields: { px }, dispose: () => canvas.getContext('webgl2')?.getExtension('WEBGL_lose_context')?.loseContext() }
+  },
+}

package/src/theme.mjs

@@ -0,0 +1 @@
+export { recipeTheme, themeTokens } from '../vendor/keel-theme.mjs'

package/src/vendor-types.d.ts

@@ -0,0 +1,24 @@
+/** A KEEL theme's colours: ramps of packed RGB, as the vendored engine computes them. */
+export interface Palette {
+  tone: string
+  surface: number[]
+  ink: number[]
+  accent: number[]
+  good: number[]
+  warn: number[]
+  bad: number[]
+  team: unknown[]
+  outline: number
+  onAccent: number
+  hues: { surface: number; accent: number }
+}
+
+/** KEEL's renderer, typed as far as a surface drives one. The rest of the vendored API is reachable, untyped. */
+export interface PixelRenderer {
+  setPalette(colours: number[][], ramps: Record<string, number[]>): void
+  setMaterials(materials: { ramp: string }[]): void
+  setWorld(world: object): void
+  setStyle(style: object): void
+  render(view: object): void
+  [other: string]: unknown
+}

package/vendor/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ravonus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/vendor/README.md

@@ -0,0 +1,8 @@
+# vendor
+
+Built by `scripts/vendor.mjs` from keel-engine 4bcccc7 (MIT, Copyright (c) 2026 ravonus; see LICENSE).
+Don't edit these files: fix KEEL and run the script again.
+
+- `keel-render.mjs`: `createPixelRenderer` from `packages/render`, with what it needs of `packages/core`.
+- `keel-theme.mjs`: `recipeTheme` and `themeTokens` from `packages/react/src/design.ts`.
+- `keel-styles.css`: `packages/react/src/styles.css`.