Keemakr UI SDK

Build server-driven module screens that Keemakr renders in Dashboard and Kee clients. Your module returns structured UI data. It does not send HTML or browser code.

1. Organize UI by surface

Keep ui/ at the module root, separate from agents:

ui/
  campaigns/
    surface.ts
    screen.ts
    campaign/
      screen.ts
  campaign-settings/
    surface.ts
    screen.ts

A surface is one complete navigable flow. Every nested screen.ts inherits its surface's availability. Put shared helpers under ui/_shared/; the generator ignores underscore-prefixed directories.

2. Declare where a surface is available

import { defineSurface } from '@keemakr/ui-sdk';

export default defineSurface({
  label: 'Campaigns',
  availableOn: ['dashboard', 'client'],
});

Use ['dashboard'] for tenant administration screens that should not appear in Kee clients. The array is required and may contain dashboard, client, or both.

3. Define screens

import { defineScreen } from '@keemakr/ui-sdk';

export default defineScreen({
  load: async () => ({
    version: 1,
    title: 'Campaigns',
    children: [{ type: 'text', value: 'Your campaigns appear here.' }],
  }),
});

Folder names are screen identities. For example, ui/campaigns/campaign/screen.ts is the campaign screen. Screen folder names must be unique across the module.

4. Generate before Eve runs

Use the SDK wrapper in the module scripts:

{
  "scripts": {
    "dev": "keemakr-ui dev -- eve dev",
    "build": "keemakr-ui build && eve build"
  }
}

The generator validates ui/, writes ui/screen-registry.ts, and synchronizes manifest.surfaces plus manifest.screenRegistry in entry.json. Do not edit those generated fields or the registry by hand. A module with no surfaces omits both fields. Removing a screen records its identity so later builds keep warning about the breaking change.

Core uses the installed manifest to filter navigation and to gate every load and action before it calls the module runtime. Availability controls UI placement. Existing authentication and roles still control who may enter Dashboard or a Kee client.

See examples/campaigns for one complete in-memory example.