@qxuken/kui (0.1.0-alpha.5)

Published 2026-09-04 03:11:09 +03:00 by qxuken in qxuken/kui

Setup this registry in your project .npmrc file:

@qxuken:registry=

To install the package using npm, run the following command:

npm install @qxuken/[email protected]

or add it to the package.json file:

"@qxuken/kui": "0.1.0-alpha.5"

For more information on the npm registry, see the documentation.

kui

kui for Node: JSX views (a custom jsx-runtime, no React) lowered into the kui IR in one call per frame, Elm-style messages as data. The library itself is documented in the kui repository.

The package is published to that Forgejo's npm registry under the @qxuken scope; route the scope there once (Forgejo does not proxy npmjs, so do not override the default registry) and install:

npm config set @qxuken:registry https://drydock9.qxuken.dev/api/packages/qxuken/npm/
npm install @qxuken/kui@alpha

Or start from the template: npm create @qxuken/kui-node my-app.

The tarball bundles the native addon for linux-x64, linux-arm64, darwin-arm64, darwin-x64 and win32-x64 under prebuilds/; native.cjs picks the one matching process.platform-process.arch. On any other platform build it from the repo (cargo build -p kui-node --release) and set KUI_NODE_LIB to the resulting library.

// tsconfig: "jsx": "react-jsx", "jsxImportSource": "@qxuken/kui"
import { createApp, runWindowed } from '@qxuken/kui';
import type { CoreMsg, UiEvent } from '@qxuken/kui';

type Model = { count: number };
// This app's own messages plus the ones the core sends by itself.
type Msg = { kind: 'add'; by: number } | { kind: 'reset' } | CoreMsg;

function update(model: Model, msg: Msg, ev: UiEvent<Msg>): Model | undefined {
  switch (msg.kind) {                       // one union, no casts
    case 'add': return { count: model.count + msg.by };
    case 'reset': return { count: 0 };
  }
}

const view = (model: Model) => (
  <box pad={24} gap={16}>
    <button onClick={{ kind: 'add', by: 1 }}>+1</button>
    <text size={20}>{`count = ${model.count}`}</text>
  </box>
);
const app = createApp({ init, update, view }, { width: 640, height: 480 });   // headless
const final = await runWindowed({ init, update, view }, { title: 'counter' }); // a window

The runWindowed loop also takes a clock — tick: { every: 250, msg: (now) => ({ kind: 'tick', now }) } — and re-renders on a tick only when update returns a new model, so a countdown is free between displayed seconds. That contract cuts both ways; see A clock below.

Testing

createApp runs the same app headless, and everything a frame produces comes back as data, so a test drives the app the way a user would and asserts on what the core produced:

Input: app.click(x, y), app.type(s), app.key(name) settle the loop for you; app.ctx.cursor / mouse / scroll / keyDown / modifiers are the raw events (a drag is cursor, mouse down, cursor, mouse up). app.ctx.setTime(s) is the clock — never set, transitions snap, which is what most tests want.
The frame: decodeQuads(app.ctx.quads()) is the display list (x, y, w, h, color, radii, kind), so "the compact tier fits its window" is every((q) => q.x + q.w <= width).
Events and sound: app.ctx.pollEvents(), and app.ctx.audioCommands() is what a window would have played.
Measurement: app.ctx.measureText(content, style, maxWidth) is what layout gives the same <text>, so a breakpoint assertion is arithmetic.
Warnings: app.warnings is every silent misconfiguration the core noticed (a grow weight with nothing to split, a transition on an unkeyed list item, a duplicate key); assert it is empty.

Windowed app checklist

Things the package already does that are easy to miss when building a real window. The full prop / element / event reference ships with the package as props.md (docs/props.md in the repository).

Hover and pressed colors are props, not queries: hoverBg, pressedBg, and hoverGroup="name" to light connected pieces together. Add transition={150} and the swap eases. <button> is exactly that data. For hover-dependent layout use onHover={tag} and react to {kind: 'hover', phase: 'enter' | 'leave'} events; win.isHovered(key) and isPressed answer for keys you got from events.
Motion that never settles is data too: keyframes takes CSS-style stops for width / height / bg / radius, cycled over transition ms in CSS's animation-direction (repeat="alternate") and held back by delay ms so siblings stagger — <box transition={1100} easing="easeInOut" repeat="alternate" delay={i * 550} width={{ grow: 0 }} keyframes={[{ width: { grow: 1 } }]} /> slides forever without the app ever waking up to flip it. Stops spread evenly unless they name at (0..1); a slot a stop leaves out falls back to the node's own prop, so [{ at: 0.5, bg: '#f5a97f' }] is a pulse.
Arrivals are data too. A node's first frame snaps, so a slide-in needed an off-screen frame and a second render; enter states the starting point instead: <box key="toast" float="viewport" transition={200} enter={{ dx: 320, bg: '#00000000' }} …/> slides in from the right and fades up on the frame it appears, and enters again after being dismissed. Add slide if it should also glide when layout moves it later — a float whose dx/dy changes eases to the new offset with slide alone.
Frame timing without the overlay: win.frameStats() is the latency HUD as data (last.viewMs, avgWorkMs, …), win.stats() the display list summary, and win.animating() tells a test when motion has settled.
Tooltips: tooltip="hint" on any box (implies hover tracking).
Per-corner radius: radius for all four, radiusTL / radiusTR / radiusBR / radiusBL after it for the exceptions.
Sound: register bytes once (win.addSound(buf) in setup, any wav/ogg/mp3/flac), then reach for it three ways. As props — clickSound and hoverSound on any box, the audio equivalent of hoverBg. As an element — <audio key="music" src={id} loop volume={0.3} /> is a playback retained by key: it plays while the view declares it, stops when the view drops it, and volume / paused changes apply to the running sound rather than restarting it, so {model.music && <audio … />} is the whole on/off story. Or imperatively — win.play(id, { volume, loop, fadeIn, tag }) returns a playback id for stop / setVolume / pause / resume, and a tag comes back as a SoundMsg ({kind: 'sound', phase: 'ended', tag}) when that playback finishes on its own, which is how a chime chains into the next state. Volumes are linear amplitude. Headless (createApp) nothing plays: ctx.audioCommands() hands you what a window would have played, which is what to assert on.
Fonts: win.loadFontsDir('fonts') then win.addSystemFont('Antonio'), or win.loadFontFile('fonts/Antonio.ttf'), win.addFont(bytes), or an installed family by name (see systemFontFamilies()); then <text font={id}>. Register in setup(win) before the first frame.
Window chrome: open with chrome: 'custom', put a <titlebar> (or your own strip with window="drag" plus <windowButtons/>) in the root; on macOS it insets past the traffic lights itself. The root box's title prop names the window each frame.
Overlays: float="below" | "above" or float={{ anchor: 'viewport', at: ['end','end'], self: ['end','end'] }} draws on top without shifting anything.
Sliders and dividers: onDrag={tag} gives { x, y, dx, dy, parent } — parent is the container rect, so a fraction needs no geometry query.
Measuring text: win.measureText('1,234', { size: 48, font }) (and ctx.measureText headless) returns { width, height, lines } — what layout gives a <text> with that content and those props, at the window's scale; pass a maxWidth to see it wrapped, and wrap / maxLines / ellipsis apply. Size a column to its widest label, or pick the tier whose labels fit, from these numbers; they follow the font.
Where did layout put it: onLayout={tag} on a keyed box brings back { kind: 'layout', x, y, w, h, parent, tag } — on its first frame and whenever the rect changes, never on a frame that left it alone, so keeping it in the model and re-rendering does not loop. A slide reports every frame it moves. It is the numbers layout already computed, handed back, for the case no prop covers yet.
Warnings: the core notices what used to fail silently — a { grow: 2 } on the only grow child (or across the parent's main axis), a transition on an unkeyed list item whose siblings changed count, two nodes on one key — and runWindowed prints each once (warnings: false in the options to stop it; win.warnings() drains them yourself). The checks are a development aid: under NODE_ENV=production they do not run at all (diagnostics: true forces them on).
Window size: win.size() gives {width, height, scale} (logical px) — in setup(win) before the first frame, and any time after. Changes arrive as {kind: 'resize', width, height, scale} events, so a model that tracks the size updates in update like anything else. Bound what the user can resize to with minWidth / minHeight / maxWidth / maxHeight next to width / height at open; either half of a pair may stand alone, and width/height are clamped into the bounds the OS will enforce.
A clock: tick: { every, msg } on runWindowed, or setTimeout toward the next boundary in your own loop; do not call update every pump. Ticks are frequent, so unlike UI events a tick re-renders only when update returns a new model — a countdown that returns undefined until the displayed second changes costs nothing in between. The same rule read backwards is the trap: a tick handler that mutates the model in place and returns undefined (the escape hatch the rest of update allows) never reaches the screen. Any non-undefined return renders, so return model after a mutation is the whole fix.
Keys: onKey on the root plus keyFocus; presses arrive as { kind: 'key', code, ... } with code a character or a name ('space', 'enter', 'f5'). onKey={null} is a sink whose events carry no tag (the same goes for onDrag, onHover and onLayout), so a root sink needs no inert message in the app's union.
Messages are yours: annotate update and the loop follows — createApp / runWindowed infer the union, so ev, dispatch and tick.msg speak it too. CoreMsg is what the core sends on its own (DragMsg, KeyMsg, HoverMsg, ModifiersMsg, changed / submit), each with the payload fields spelled out; pollEvents<KeyMsg<Tag>>() types a raw poll the same way. To have the payload props checked at the node as well, register the app's own union once:
```
declare module '@qxuken/kui/jsx-runtime' {
  interface KuiMsg { msg: MyMsg }
}
```
onClick then takes exactly MyMsg (and onDrag / onHover / onKey / onLayout take MyMsg | null) rather than any plain data, so a typo fails where it is written. Register the messages you wrote, not MyMsg | CoreMsg: CoreMsg is typed in terms of the registration (its tag fields carry your messages), so naming it there makes the alias circular — keep that union for update. It is a program-wide declaration (one app per tsconfig); left out, payload props stay untyped and nothing else changes.