@keemakr/ui-sdk 0.1.1 → 1.0.0-dev-20260807074219

package/README.md

@@ -0,0 +1,79 @@
+# 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:
+
+```text
+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
+
+```ts
+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
+
+```ts
+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:
+
+```json
+{
+  "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`](./examples/campaigns) for one complete in-memory example.

package/dist/build.d.ts

@@ -0,0 +1,9 @@
+import { type UiManifest } from './schema.js';
+export interface BuildModuleUiResult {
+    manifest: UiManifest;
+    registryPath: string;
+    entryPath: string;
+    removedScreens: string[];
+}
+/** Validate root ui/, generate its runtime registry, and synchronize entry.json. */
+export declare function buildModuleUi(projectRoot?: string): Promise<BuildModuleUiResult>;

package/dist/build.js

@@ -0,0 +1,264 @@
+import { readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, relative, sep } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import ts from 'typescript';
+import { surfaceDefinitionSchema, uiManifestSchema, } from './schema.js';
+const SLUG = /^[a-z][a-z0-9_-]*$/;
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const REMOVED_SCREENS_META_KEY = 'uiSdkRemovedScreens';
+function unwrap(expression) {
+    if (ts.isParenthesizedExpression(expression) ||
+        ts.isAsExpression(expression) ||
+        ts.isSatisfiesExpression(expression)) {
+        return unwrap(expression.expression);
+    }
+    return expression;
+}
+function literalValue(expression) {
+    const value = unwrap(expression);
+    if (ts.isStringLiteralLike(value))
+        return value.text;
+    if (value.kind === ts.SyntaxKind.TrueKeyword)
+        return true;
+    if (value.kind === ts.SyntaxKind.FalseKeyword)
+        return false;
+    if (ts.isArrayLiteralExpression(value))
+        return value.elements.map(literalValue);
+    throw new Error('surface.ts values must be string or array literals');
+}
+async function readSurfaceDefinition(path) {
+    const source = ts.createSourceFile(path, await readFile(path, 'utf8'), ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    let object;
+    for (const statement of source.statements) {
+        if (!ts.isExportAssignment(statement))
+            continue;
+        const exported = unwrap(statement.expression);
+        if (!ts.isCallExpression(exported) || exported.arguments.length !== 1)
+            continue;
+        if (!ts.isIdentifier(exported.expression) || exported.expression.text !== 'defineSurface')
+            continue;
+        const argument = unwrap(exported.arguments[0]);
+        if (ts.isObjectLiteralExpression(argument))
+            object = argument;
+    }
+    if (!object) {
+        throw new Error(`${path}: default export must be defineSurface({ ... })`);
+    }
+    const raw = {};
+    for (const property of object.properties) {
+        if (!ts.isPropertyAssignment(property)) {
+            throw new Error(`${path}: surface properties must use key: value syntax`);
+        }
+        const name = property.name;
+        if (!ts.isIdentifier(name) && !ts.isStringLiteral(name)) {
+            throw new Error(`${path}: surface property names must be static`);
+        }
+        raw[name.text] = literalValue(property.initializer);
+    }
+    const allowed = new Set(['label', 'icon', 'description', 'availableOn']);
+    for (const key of Object.keys(raw)) {
+        if (!allowed.has(key))
+            throw new Error(`${path}: unknown surface property "${key}"`);
+    }
+    const parsed = surfaceDefinitionSchema.safeParse(raw);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        throw new Error(`${path}: ${issue?.path.join('.') || 'surface'} ${issue?.message ?? 'is invalid'}`);
+    }
+    return parsed.data;
+}
+async function isFile(path) {
+    return stat(path)
+        .then((value) => value.isFile())
+        .catch(() => false);
+}
+async function collectScreenFiles(directory) {
+    const out = [];
+    if (await isFile(join(directory, 'screen.ts')))
+        out.push(join(directory, 'screen.ts'));
+    const entries = await readdir(directory, { withFileTypes: true });
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name.startsWith('_'))
+            continue;
+        const child = join(directory, entry.name);
+        if (await isFile(join(child, 'surface.ts'))) {
+            throw new Error(`${join(child, 'surface.ts')}: nested surfaces are not allowed`);
+        }
+        out.push(...(await collectScreenFiles(child)));
+    }
+    return out;
+}
+function moduleSpecifier(fromDirectory, file) {
+    const value = relative(fromDirectory, file).split(sep).join('/').replace(/\.ts$/, '.js');
+    return value.startsWith('.') ? value : `./${value}`;
+}
+function propertyKey(key) {
+    return IDENTIFIER.test(key) ? key : `'${key}'`;
+}
+async function readIfPresent(path) {
+    return readFile(path, 'utf8').catch((error) => {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+}
+function temporaryPath(path, index) {
+    return `${path}.keemakr-ui-${process.pid}-${Date.now()}-${index}.tmp`;
+}
+async function restoreOutput(output) {
+    if (output.previous === undefined) {
+        await rm(output.path, { force: true });
+        return;
+    }
+    const restorePath = temporaryPath(output.path, -1);
+    await writeFile(restorePath, output.previous);
+    await rename(restorePath, output.path);
+}
+/**
+ * Prepare every generated file before replacing either live output. A process
+ * can still die between two renames, but ordinary write/rename failures restore
+ * the previous pair rather than leaving one generated contract half-updated.
+ */
+async function replaceGeneratedOutputs(outputs) {
+    const changed = [];
+    for (const output of outputs) {
+        const previous = await readIfPresent(output.path);
+        if (previous !== output.contents)
+            changed.push({ ...output, previous });
+    }
+    try {
+        for (const [index, output] of changed.entries()) {
+            if (output.contents === undefined)
+                continue;
+            output.temporaryPath = temporaryPath(output.path, index);
+            await writeFile(output.temporaryPath, output.contents);
+        }
+        const committed = [];
+        try {
+            for (const output of changed) {
+                if (output.temporaryPath)
+                    await rename(output.temporaryPath, output.path);
+                else
+                    await rm(output.path, { force: true });
+                committed.push(output);
+            }
+        }
+        catch (error) {
+            const restores = await Promise.allSettled(committed.reverse().map(restoreOutput));
+            const restoreFailure = restores.find((result) => result.status === 'rejected');
+            if (restoreFailure?.status === 'rejected') {
+                throw new AggregateError([error, restoreFailure.reason], 'generated UI outputs could not be committed or restored');
+            }
+            throw error;
+        }
+    }
+    finally {
+        await Promise.all(changed.flatMap((output) => output.temporaryPath ? [rm(output.temporaryPath, { force: true })] : []));
+    }
+}
+function stringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string') ? value : [];
+}
+/** Validate root ui/, generate its runtime registry, and synchronize entry.json. */
+export async function buildModuleUi(projectRoot = process.cwd()) {
+    const uiRoot = join(projectRoot, 'ui');
+    const entryPath = join(projectRoot, 'entry.json');
+    const entries = await readdir(uiRoot, { withFileTypes: true }).catch((error) => {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    });
+    const surfaces = [];
+    const screenRegistry = [];
+    const registryImports = [];
+    const seenScreens = new Map();
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name.startsWith('_'))
+            continue;
+        if (!SLUG.test(entry.name))
+            throw new Error(`surface directory "${entry.name}" is not a slug`);
+        const surfaceDirectory = join(uiRoot, entry.name);
+        const definitionPath = join(surfaceDirectory, 'surface.ts');
+        const rootScreenPath = join(surfaceDirectory, 'screen.ts');
+        if (!(await isFile(definitionPath)))
+            throw new Error(`${definitionPath}: file is required`);
+        if (!(await isFile(rootScreenPath)))
+            throw new Error(`${rootScreenPath}: file is required`);
+        const definition = await readSurfaceDefinition(definitionPath);
+        surfaces.push({ key: entry.name, screen: entry.name, ...definition });
+        for (const file of await collectScreenFiles(surfaceDirectory)) {
+            const screen = basename(dirname(file));
+            if (!SLUG.test(screen))
+                throw new Error(`${file}: screen directory "${screen}" is not a slug`);
+            const previous = seenScreens.get(screen);
+            if (previous) {
+                throw new Error(`duplicate screen identity "${screen}" in ${previous} and ${file}`);
+            }
+            seenScreens.set(screen, file);
+            screenRegistry.push({ screen, surface: entry.name });
+            registryImports.push({ screen, file });
+        }
+    }
+    screenRegistry.sort((a, b) => a.screen.localeCompare(b.screen));
+    registryImports.sort((a, b) => a.screen.localeCompare(b.screen));
+    const manifest = surfaces.length === 0
+        ? { surfaces, screenRegistry }
+        : uiManifestSchema.parse({ surfaces, screenRegistry });
+    const entrySource = await readFile(entryPath, 'utf8');
+    const originalEntryManifest = JSON.parse(entrySource);
+    const entryManifest = JSON.parse(entrySource);
+    if (!entryManifest.manifest || typeof entryManifest.manifest !== 'object') {
+        throw new Error(`${entryPath}: manifest object is required`);
+    }
+    const registryPath = join(uiRoot, 'screen-registry.ts');
+    const imports = registryImports
+        .map((item, index) => `import screen${index} from '${moduleSpecifier(uiRoot, item.file)}';`)
+        .join('\n');
+    const properties = registryImports
+        .map((item, index) => `  ${propertyKey(item.screen)}: screen${index},`)
+        .join('\n');
+    const registryContents = surfaces.length === 0
+        ? undefined
+        : `// Generated by @keemakr/ui-sdk. Do not edit.\n${imports}\n\nexport const SCREENS = {\n${properties}\n} as const;\n`;
+    const previousScreens = Array.isArray(entryManifest.manifest.screenRegistry)
+        ? entryManifest.manifest.screenRegistry.flatMap((item) => item && typeof item === 'object' && 'screen' in item && typeof item.screen === 'string'
+            ? [item.screen]
+            : [])
+        : [];
+    const currentScreens = new Set(manifest.screenRegistry.map((item) => item.screen));
+    const meta = entryManifest.manifest.meta && typeof entryManifest.manifest.meta === 'object'
+        ? entryManifest.manifest.meta
+        : {};
+    const removedScreens = [
+        ...new Set([
+            ...stringArray(meta[REMOVED_SCREENS_META_KEY]),
+            ...previousScreens.filter((screen) => !currentScreens.has(screen)),
+        ]),
+    ]
+        .filter((screen) => !currentScreens.has(screen))
+        .sort();
+    if (surfaces.length === 0) {
+        delete entryManifest.manifest.surfaces;
+        delete entryManifest.manifest.screenRegistry;
+    }
+    else {
+        entryManifest.manifest.surfaces = manifest.surfaces;
+        entryManifest.manifest.screenRegistry = manifest.screenRegistry;
+    }
+    if (removedScreens.length > 0) {
+        entryManifest.manifest.meta = { ...meta, [REMOVED_SCREENS_META_KEY]: removedScreens };
+    }
+    else if (REMOVED_SCREENS_META_KEY in meta) {
+        const remainingMeta = { ...meta };
+        delete remainingMeta[REMOVED_SCREENS_META_KEY];
+        entryManifest.manifest.meta = remainingMeta;
+    }
+    const entryContents = isDeepStrictEqual(entryManifest, originalEntryManifest)
+        ? entrySource
+        : `${JSON.stringify(entryManifest, null, 2)}\n`;
+    await replaceGeneratedOutputs([
+        { path: registryPath, contents: registryContents },
+        { path: entryPath, contents: entryContents },
+    ]);
+    return { manifest, registryPath, entryPath, removedScreens };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+import { watch } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { buildModuleUi } from './build.js';
+async function build() {
+    const result = await buildModuleUi();
+    if (result.removedScreens.length > 0) {
+        console.warn(`Warning: removed screen identities: ${result.removedScreens.join(', ')}. Treat path renames as breaking changes.`);
+    }
+    console.log(`Built ${result.manifest.surfaces.length} UI surface(s) and ${result.manifest.screenRegistry.length} screen(s).`);
+}
+function createRebuildScheduler() {
+    let buildInFlight;
+    let dirty = false;
+    return () => {
+        if (buildInFlight) {
+            dirty = true;
+            return;
+        }
+        buildInFlight = (async () => {
+            do {
+                dirty = false;
+                try {
+                    await build();
+                }
+                catch (error) {
+                    console.error(error instanceof Error ? error.message : error);
+                }
+            } while (dirty);
+        })();
+        void buildInFlight.finally(() => {
+            buildInFlight = undefined;
+        });
+    };
+}
+function createUiWatcher(onChange) {
+    const directory = join(process.cwd(), 'ui');
+    try {
+        return watch(directory, { recursive: true }, (_event, filename) => {
+            if (!filename || filename.endsWith('screen-registry.ts'))
+                return;
+            onChange();
+        });
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Unable to recursively watch ${directory}. keemakr-ui dev requires Node >=20.9 with recursive fs.watch support on this platform. Upgrade Node or run \"keemakr-ui build\" after UI changes. (${detail})`);
+    }
+}
+async function dev(command) {
+    await build();
+    let timer;
+    const requestRebuild = createRebuildScheduler();
+    const watcher = createUiWatcher(() => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            requestRebuild();
+        }, 50);
+    });
+    let watcherClosed = false;
+    const closeWatcher = () => {
+        if (timer) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+        if (watcherClosed)
+            return;
+        watcherClosed = true;
+        watcher.close();
+    };
+    let child;
+    watcher.once('error', (error) => {
+        closeWatcher();
+        console.error(`UI watcher stopped: ${error.message}`);
+        child?.kill('SIGTERM');
+        process.exitCode = 1;
+    });
+    const childCommand = command[0] ?? 'eve';
+    const childArgs = command.length > 0 ? command.slice(1) : ['dev'];
+    child = spawn(childCommand, childArgs, { stdio: 'inherit' });
+    const stop = (signal) => {
+        closeWatcher();
+        child?.kill(signal);
+    };
+    process.once('SIGINT', () => stop('SIGINT'));
+    process.once('SIGTERM', () => stop('SIGTERM'));
+    child.once('error', (error) => {
+        closeWatcher();
+        console.error(`Unable to start ${childCommand}: ${error.message}`);
+        process.exitCode = 1;
+    });
+    child.once('exit', (code, signal) => {
+        closeWatcher();
+        process.exitCode = signal ? 1 : (code ?? 1);
+    });
+}
+async function main() {
+    const [command = 'build', ...args] = process.argv.slice(2);
+    if (command === 'build') {
+        await build();
+    }
+    else if (command === 'dev') {
+        const separator = args.indexOf('--');
+        await dev(separator === -1 ? args : args.slice(separator + 1));
+    }
+    else {
+        throw new Error('Usage: keemakr-ui build | keemakr-ui dev -- eve dev');
+    }
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+});

package/dist/define.d.ts

@@ -1,19 +1,4 @@
-/**
- * defineScreen — the module-dev half of the contract.
- *
- * A screen is two things: a `load` that returns a ScreenTree, and named
- * `actions` the tree's buttons/forms reference by key. Handlers run
- * server-side in the module's own eve deployment; keemakr-core calls them
- * through the grant-authed screens channel and validates every response
- * against the schemas in ./schema before rendering.
- *
- * `Ctx` is generic on purpose: this package depends on nothing. The eve
- * channel adapter (shipped alongside the reference module) binds Ctx to the
- * eve tool ctx, so inside handlers `useKee(ctx)` works exactly as it does in
- * agent tools — tenant and scopes come from the verified grant, never from
- * params.
- */
-import type { ActionResultInput, ScreenTreeInput } from './schema.js';
+import type { ActionResultInput, ScreenTreeInput, SurfaceDefinition } from './schema.js';
 export type ScreenParams = Record<string, string>;
 export type LoadHandler<Ctx> = (ctx: Ctx, params: ScreenParams) => ScreenTreeInput | Promise<ScreenTreeInput>;
 export type ActionHandler<Ctx> = (ctx: Ctx, input: Record<string, unknown>, params: ScreenParams) => ActionResultInput | Promise<ActionResultInput>;
@@ -26,3 +11,5 @@ export interface ScreenDefinition<Ctx = unknown> {
  * cheap authoring-time validation, not runtime behavior.
  */
 export declare function defineScreen<Ctx = unknown>(screen: ScreenDefinition<Ctx>): ScreenDefinition<Ctx>;
+/** Define surface metadata. The filesystem supplies its key, root screen, and child ownership. */
+export declare function defineSurface(surface: SurfaceDefinition): SurfaceDefinition;

package/dist/define.js

@@ -1,3 +1,19 @@
+/**
+ * defineScreen — the module-dev half of the contract.
+ *
+ * A screen is two things: a `load` that returns a ScreenTree, and named
+ * `actions` the tree's buttons/forms reference by key. Handlers run
+ * server-side in the module's own eve deployment; keemakr-core calls them
+ * through the grant-authed screens channel and validates every response
+ * against the schemas in ./schema before rendering.
+ *
+ * `Ctx` is generic on purpose: this package depends on nothing. The eve
+ * channel adapter (shipped alongside the reference module) binds Ctx to the
+ * eve tool ctx, so inside handlers `useKee(ctx)` works exactly as it does in
+ * agent tools — tenant and scopes come from the verified grant, never from
+ * params.
+ */
+import { surfaceDefinitionSchema } from './schema.js';
 const ACTION_KEY = /^[a-z][a-z0-9_-]*$/;
 /**
  * Identity function (the defineProvider pattern): exists for inference and
@@ -11,3 +27,8 @@ export function defineScreen(screen) {
     }
     return screen;
 }
+/** Define surface metadata. The filesystem supplies its key, root screen, and child ownership. */
+export function defineSurface(surface) {
+    surfaceDefinitionSchema.parse(surface);
+    return surface;
+}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { UI_SCHEMA_VERSION, pressSchema, buttonSchema, cellSchema, nodeSchema, screenTreeSchema, actionResultSchema, screenLoadRequestSchema, screenLoadResponseSchema, screenActionRequestSchema, surfaceSchema, } from './schema.js';
-export type { Press, ScreenNode, ScreenTree, ActionResult, Surface, ScreenTreeInput, ActionResultInput, } from './schema.js';
-export { defineScreen } from './define.js';
+export { UI_SCHEMA_VERSION, pressSchema, buttonSchema, cellSchema, nodeSchema, screenTreeSchema, actionResultSchema, screenLoadRequestSchema, screenLoadResponseSchema, screenActionRequestSchema, interfaceFamilySchema, surfaceDefinitionSchema, surfaceSchema, screenRegistrationSchema, uiManifestSchema, } from './schema.js';
+export type { Press, ScreenNode, ScreenTree, ActionResult, InterfaceFamily, SurfaceDefinition, Surface, ScreenRegistration, UiManifest, ScreenTreeInput, ActionResultInput, } from './schema.js';
+export { defineScreen, defineSurface } from './define.js';
 export type { ScreenDefinition, ScreenParams, LoadHandler, ActionHandler } from './define.js';

package/dist/index.js

@@ -6,5 +6,5 @@
 //                    platform components, proxies load/action with a grant
 //
 // Module code never ships to the browser. UI is data, not code.
-export { UI_SCHEMA_VERSION, pressSchema, buttonSchema, cellSchema, nodeSchema, screenTreeSchema, actionResultSchema, screenLoadRequestSchema, screenLoadResponseSchema, screenActionRequestSchema, surfaceSchema, } from './schema.js';
-export { defineScreen } from './define.js';
+export { UI_SCHEMA_VERSION, pressSchema, buttonSchema, cellSchema, nodeSchema, screenTreeSchema, actionResultSchema, screenLoadRequestSchema, screenLoadResponseSchema, screenActionRequestSchema, interfaceFamilySchema, surfaceDefinitionSchema, surfaceSchema, screenRegistrationSchema, uiManifestSchema, } from './schema.js';
+export { defineScreen, defineSurface } from './define.js';

package/dist/schema.d.ts

@@ -302,22 +302,65 @@ export declare const screenActionRequestSchema: z.ZodObject<{
     input: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     idempotencyKey: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+export declare const interfaceFamilySchema: z.ZodEnum<{
+    dashboard: "dashboard";
+    client: "client";
+}>;
+export declare const surfaceDefinitionSchema: z.ZodObject<{
+    label: z.ZodString;
+    icon: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    availableOn: z.ZodArray<z.ZodEnum<{
+        dashboard: "dashboard";
+        client: "client";
+    }>>;
+}, z.core.$strip>;
 /**
  * Manifest addition: `manifest.surfaces[]` in entry.json. Each surface is a
  * side-menu entry pointing at an entry screen. Core's marketplace
  * validateSubmission composes this in (wired in the proxy phase).
  */
 export declare const surfaceSchema: z.ZodObject<{
-    key: z.ZodString;
     label: z.ZodString;
     icon: z.ZodOptional<z.ZodString>;
-    screen: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
+    availableOn: z.ZodArray<z.ZodEnum<{
+        dashboard: "dashboard";
+        client: "client";
+    }>>;
+    key: z.ZodString;
+    screen: z.ZodString;
+}, z.core.$strip>;
+export declare const screenRegistrationSchema: z.ZodObject<{
+    screen: z.ZodString;
+    surface: z.ZodString;
+}, z.core.$strip>;
+/** The complete generated UI portion of a module manifest. */
+export declare const uiManifestSchema: z.ZodObject<{
+    surfaces: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        icon: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        availableOn: z.ZodArray<z.ZodEnum<{
+            dashboard: "dashboard";
+            client: "client";
+        }>>;
+        key: z.ZodString;
+        screen: z.ZodString;
+    }, z.core.$strip>>;
+    screenRegistry: z.ZodArray<z.ZodObject<{
+        screen: z.ZodString;
+        surface: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type Press = z.infer<typeof pressSchema>;
 export type ScreenTree = z.infer<typeof screenTreeSchema>;
 export type ActionResult = z.infer<typeof actionResultSchema>;
+export type InterfaceFamily = z.infer<typeof interfaceFamilySchema>;
+export type SurfaceDefinition = z.infer<typeof surfaceDefinitionSchema>;
 export type Surface = z.infer<typeof surfaceSchema>;
+export type ScreenRegistration = z.infer<typeof screenRegistrationSchema>;
+export type UiManifest = z.infer<typeof uiManifestSchema>;
 export type ScreenTreeInput = z.input<typeof screenTreeSchema>;
 export type ActionResultInput = z.input<typeof actionResultSchema>;
 export {};

package/dist/schema.js

@@ -235,16 +235,76 @@ export const screenActionRequestSchema = z.object({
      *  half of at-least-once). Optional for runtime version-skew tolerance. */
     idempotencyKey: z.string().max(200).optional(),
 });
+export const interfaceFamilySchema = z.enum(['dashboard', 'client']);
+export const surfaceDefinitionSchema = z.object({
+    label: z.string().min(1).max(60),
+    /** Lucide icon name, same convention as entry.json `icon`. */
+    icon: z.string().max(60).optional(),
+    description: z.string().max(200).optional(),
+    availableOn: z
+        .array(interfaceFamilySchema)
+        .min(1)
+        .max(2)
+        .refine((families) => new Set(families).size === families.length, {
+        message: 'interface families must be unique',
+    }),
+});
 /**
  * Manifest addition: `manifest.surfaces[]` in entry.json. Each surface is a
  * side-menu entry pointing at an entry screen. Core's marketplace
  * validateSubmission composes this in (wired in the proxy phase).
  */
-export const surfaceSchema = z.object({
+export const surfaceSchema = surfaceDefinitionSchema.extend({
     key: slug,
-    label: z.string().max(60),
-    /** Lucide icon name, same convention as entry.json `icon`. */
-    icon: z.string().max(60).optional(),
     screen: slug,
-    description: z.string().max(200).optional(),
+});
+export const screenRegistrationSchema = z.object({
+    screen: slug,
+    surface: slug,
+});
+/** The complete generated UI portion of a module manifest. */
+export const uiManifestSchema = z
+    .object({
+    surfaces: z.array(surfaceSchema).min(1),
+    screenRegistry: z.array(screenRegistrationSchema).min(1).max(256),
+})
+    .superRefine((manifest, ctx) => {
+    const surfaceKeys = new Set();
+    for (const [index, surface] of manifest.surfaces.entries()) {
+        if (surfaceKeys.has(surface.key)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['surfaces', index, 'key'],
+                message: `duplicate surface key "${surface.key}"`,
+            });
+        }
+        surfaceKeys.add(surface.key);
+    }
+    const screens = new Map();
+    for (const [index, registration] of manifest.screenRegistry.entries()) {
+        if (!surfaceKeys.has(registration.surface)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['screenRegistry', index, 'surface'],
+                message: `unknown surface "${registration.surface}"`,
+            });
+        }
+        if (screens.has(registration.screen)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['screenRegistry', index, 'screen'],
+                message: `duplicate screen identity "${registration.screen}"`,
+            });
+        }
+        screens.set(registration.screen, registration.surface);
+    }
+    for (const [index, surface] of manifest.surfaces.entries()) {
+        if (screens.get(surface.screen) !== surface.key) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['surfaces', index, 'screen'],
+                message: `root screen "${surface.screen}" must be registered to surface "${surface.key}"`,
+            });
+        }
+    }
 });

package/examples/campaigns/README.md

@@ -0,0 +1,17 @@
+# Campaigns example
+
+This example has:
+
+- a Campaigns surface available in Dashboard and Kee clients;
+- a nested campaign detail screen that inherits that availability;
+- a separate Campaign settings surface available only in Dashboard;
+- one in-memory pause action.
+
+From this directory, generate the manifest and registry, then run the demo:
+
+```bash
+npx keemakr-ui build
+npx tsx demo.ts
+```
+
+No database or external service is required.

package/examples/campaigns/demo.ts

@@ -0,0 +1,13 @@
+import { SCREENS } from './ui/screen-registry.js';
+
+async function main() {
+  const params = { id: 'summer-launch' };
+  console.log(await SCREENS.campaign.load({}, params));
+  console.log(await SCREENS.campaign.actions?.pause?.({}, {}, params));
+  console.log(await SCREENS.campaign.load({}, params));
+}
+
+void main().catch((error: unknown) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/examples/campaigns/entry.json

@@ -0,0 +1,53 @@
+{
+  "slug": "campaigns-example",
+  "display_name": "Campaigns example",
+  "visibility": "public",
+  "runtime": {
+    "kind": "eve",
+    "url": "http://localhost:3210",
+    "status": "dev"
+  },
+  "manifest": {
+    "department": {
+      "key": "sales",
+      "label": "Sales"
+    },
+    "agents": [
+      {
+        "key": "campaign-manager",
+        "display_name": "Campaign manager"
+      }
+    ],
+    "surfaces": [
+      {
+        "label": "Campaign settings",
+        "description": "Configure tenant campaign defaults.",
+        "availableOn": ["dashboard"],
+        "key": "campaign-settings",
+        "screen": "campaign-settings"
+      },
+      {
+        "label": "Campaigns",
+        "description": "Create and monitor campaigns.",
+        "availableOn": ["dashboard", "client"],
+        "key": "campaigns",
+        "screen": "campaigns"
+      }
+    ],
+    "screenRegistry": [
+      {
+        "screen": "campaign",
+        "surface": "campaigns"
+      },
+      {
+        "screen": "campaign-settings",
+        "surface": "campaign-settings"
+      },
+      {
+        "screen": "campaigns",
+        "surface": "campaigns"
+      }
+    ]
+  },
+  "dependencies": []
+}

package/examples/campaigns/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["demo.ts", "ui/**/*.ts"]
+}

package/examples/campaigns/ui/campaign-settings/screen.ts

@@ -0,0 +1,9 @@
+import { defineScreen } from '@keemakr/ui-sdk';
+
+export default defineScreen({
+  load: async () => ({
+    version: 1,
+    title: 'Campaign settings',
+    children: [{ type: 'text', value: 'Default daily send limit: 100' }],
+  }),
+});

package/examples/campaigns/ui/campaign-settings/surface.ts

@@ -0,0 +1,7 @@
+import { defineSurface } from '@keemakr/ui-sdk';
+
+export default defineSurface({
+  label: 'Campaign settings',
+  description: 'Configure tenant campaign defaults.',
+  availableOn: ['dashboard'],
+});

package/examples/campaigns/ui/campaigns/campaign/screen.ts

@@ -0,0 +1,29 @@
+import { defineScreen } from '@keemakr/ui-sdk';
+import { campaigns } from '../../data.js';
+
+export default defineScreen({
+  load: async (_ctx, params) => {
+    const campaign = campaigns.find((item) => item.id === params.id);
+    return {
+      version: 1,
+      title: campaign?.name ?? 'Campaign not found',
+      children: campaign
+        ? [
+            { type: 'text' as const, value: `Status: ${campaign.status}` },
+            {
+              type: 'button' as const,
+              label: 'Pause campaign',
+              onPress: { kind: 'action' as const, action: 'pause' },
+            },
+          ]
+        : [{ type: 'text' as const, value: 'This campaign does not exist.' }],
+    };
+  },
+  actions: {
+    pause: async (_ctx, _input, params) => {
+      const campaign = campaigns.find((item) => item.id === params.id);
+      if (campaign) campaign.status = 'paused';
+      return { toast: campaign ? 'Campaign paused.' : 'Campaign not found.', refresh: true };
+    },
+  },
+});

package/examples/campaigns/ui/campaigns/screen.ts

@@ -0,0 +1,27 @@
+import { defineScreen } from '@keemakr/ui-sdk';
+import { campaigns } from '../data.js';
+
+export default defineScreen({
+  load: async () => ({
+    version: 1,
+    title: 'Campaigns',
+    children: [
+      {
+        type: 'table',
+        columns: [
+          { key: 'name', label: 'Campaign' },
+          { key: 'status', label: 'Status' },
+        ],
+        rows: campaigns.map((campaign) => ({
+          key: campaign.id,
+          cells: {
+            name: { kind: 'text', value: campaign.name },
+            status: { kind: 'badge', value: campaign.status },
+          },
+          onPress: { kind: 'navigate', screen: 'campaign', params: { id: campaign.id } },
+        })),
+        empty: 'No campaigns yet.',
+      },
+    ],
+  }),
+});

package/examples/campaigns/ui/campaigns/surface.ts

@@ -0,0 +1,7 @@
+import { defineSurface } from '@keemakr/ui-sdk';
+
+export default defineSurface({
+  label: 'Campaigns',
+  description: 'Create and monitor campaigns.',
+  availableOn: ['dashboard', 'client'],
+});

package/examples/campaigns/ui/data.ts

@@ -0,0 +1,9 @@
+export interface Campaign {
+  id: string;
+  name: string;
+  status: 'active' | 'paused';
+}
+
+export const campaigns: Campaign[] = [
+  { id: 'summer-launch', name: 'Summer launch', status: 'active' },
+];

package/examples/campaigns/ui/screen-registry.ts

@@ -0,0 +1,10 @@
+// Generated by @keemakr/ui-sdk. Do not edit.
+import screen0 from './campaigns/campaign/screen.js';
+import screen1 from './campaign-settings/screen.js';
+import screen2 from './campaigns/screen.js';
+
+export const SCREENS = {
+  campaign: screen0,
+  'campaign-settings': screen1,
+  campaigns: screen2,
+} as const;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keemakr/ui-sdk",
-  "version": "0.1.1",
+  "version": "1.0.0-dev-20260807074219",
   "description": "Product screens for keemakr marketplace modules: a versioned, server-driven UI tree schema plus defineScreen() handlers. Module code never ships to the browser — keemakr-core validates the tree and renders it with platform components.",
   "license": "MIT",
   "type": "module",
@@ -11,11 +11,20 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./build": {
+      "types": "./dist/build.d.ts",
+      "import": "./dist/build.js",
+      "default": "./dist/build.js"
     }
   },
+  "bin": {
+    "keemakr-ui": "./dist/cli.js"
+  },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "examples"
   ],
   "publishConfig": {
     "access": "public"
@@ -33,9 +42,11 @@
   "peerDependencies": {
     "zod": "^4.4.3"
   },
+  "dependencies": {
+    "typescript": "^5"
+  },
   "devDependencies": {
     "@types/node": "^20.19.43",
-    "typescript": "^5",
     "zod": "^4.4.3"
   },
   "engines": {