@keemakr/ui-sdk 0.1.0

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@keemakr/ui-sdk",
+  "version": "0.1.0",
+  "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",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fsztpartners/keemakr.git",
+    "directory": "packages/ui-sdk"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "typescript": "^5",
+    "zod": "^4.4.3"
+  },
+  "engines": {
+    "node": ">=20.9"
+  }
+}

package/src/define.ts

@@ -0,0 +1,51 @@
+/**
+ * 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';
+
+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>;
+
+export interface ScreenDefinition<Ctx = unknown> {
+  load: LoadHandler<Ctx>;
+  actions?: Record<string, ActionHandler<Ctx>>;
+}
+
+const ACTION_KEY = /^[a-z][a-z0-9_-]*$/;
+
+/**
+ * Identity function (the defineProvider pattern): exists for inference and
+ * cheap authoring-time validation, not runtime behavior.
+ */
+export function defineScreen<Ctx = unknown>(screen: ScreenDefinition<Ctx>): ScreenDefinition<Ctx> {
+  for (const key of Object.keys(screen.actions ?? {})) {
+    if (!ACTION_KEY.test(key) || key.length > 64) {
+      throw new Error(
+        `defineScreen: action key "${key}" must be a lowercase slug (a-z, 0-9, -, _), max 64 chars`,
+      );
+    }
+  }
+  return screen;
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+// @keemakr/ui-sdk — product screens for keemakr marketplace modules.
+//
+// One contract, two consumers (the operator-sdk pattern):
+//   - module devs:   defineScreen() handlers running in their eve deployment
+//   - keemakr-core:  validates trees/results with these schemas, renders with
+//                    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';
+
+export type {
+  Press,
+  ScreenNode,
+  ScreenTree,
+  ActionResult,
+  Surface,
+  ScreenTreeInput,
+  ActionResultInput,
+} from './schema';
+
+export { defineScreen } from './define';
+
+export type { ScreenDefinition, ScreenParams, LoadHandler, ActionHandler } from './define';

package/src/schema.ts

@@ -0,0 +1,316 @@
+/**
+ * The server-driven UI contract between a module runtime and keemakr-core.
+ *
+ * A module's `load` handler returns a ScreenTree; core validates it against
+ * this schema BEFORE rendering — that validation is the security boundary.
+ * Nothing here ever becomes raw HTML: every node maps to a platform-owned
+ * component, so module output is data, not code.
+ *
+ * Versioning: `version` is a literal. A breaking change to any node shape
+ * bumps UI_SCHEMA_VERSION and adds a new literal; core keeps rendering old
+ * versions until modules migrate.
+ */
+import { z } from 'zod';
+
+export const UI_SCHEMA_VERSION = 1;
+
+const slug = z
+  .string()
+  .regex(/^[a-z][a-z0-9_-]*$/, 'lowercase slug (a-z, 0-9, -, _)')
+  .max(64);
+
+/** What a button (or table row) does when pressed. */
+export const pressSchema = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('action'),
+    /** Key into the screen's `actions` map on the module runtime. */
+    action: slug,
+    input: z.record(z.string(), z.unknown()).optional(),
+    /** If set, core shows this confirmation before dispatching. */
+    confirm: z.string().max(500).optional(),
+  }),
+  z.object({
+    kind: z.literal('navigate'),
+    /** Another screen key of the same module. */
+    screen: slug,
+    params: z.record(z.string(), z.string()).optional(),
+  }),
+]);
+
+const tone = z.enum(['default', 'success', 'warning', 'destructive']);
+
+export const buttonSchema = z.object({
+  type: z.literal('button'),
+  label: z.string().max(80),
+  onPress: pressSchema,
+  variant: z.enum(['primary', 'secondary', 'destructive']).default('secondary'),
+});
+
+/** A table cell. Dates are ISO 8601; core formats them tenant-locale-aware. */
+export const cellSchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('text'), value: z.string().max(500) }),
+  z.object({ kind: z.literal('badge'), value: z.string().max(40), tone: tone.default('default') }),
+  z.object({ kind: z.literal('date'), value: z.iso.datetime() }),
+]);
+
+const choiceCardsSchema = z.object({
+  type: z.literal('choice_cards'),
+  choices: z
+    .array(
+      z.object({
+        id: z.string().min(1).max(64),
+        title: z.string().min(1).max(120),
+        description: z.string().max(500).optional(),
+        meta: z.string().max(120).optional(),
+        selected: z.boolean().default(false),
+        onPress: pressSchema,
+      }),
+    )
+    .min(1)
+    .max(20),
+});
+
+const progressSchema = z.object({
+  type: z.literal('progress'),
+  steps: z
+    .array(
+      z.object({
+        label: z.string().min(1).max(200),
+        status: z.enum(['pending', 'active', 'done', 'error']),
+        detail: z.string().max(1000).optional(),
+      }),
+    )
+    .min(1)
+    .max(100),
+});
+
+const chartSchema = z
+  .object({
+    type: z.literal('chart'),
+    chartType: z.enum(['bar', 'line']),
+    title: z.string().max(120).optional(),
+    categories: z.array(z.string().max(80)).min(1).max(50),
+    series: z
+      .array(
+        z.object({
+          name: z.string().min(1).max(80),
+          values: z.array(z.number().finite()).min(1).max(50),
+        }),
+      )
+      .min(1)
+      .max(8),
+  })
+  .superRefine((chart, ctx) => {
+    for (let i = 0; i < chart.series.length; i += 1) {
+      if (chart.series[i].values.length !== chart.categories.length) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['series', i, 'values'],
+          message: 'must contain one value per category',
+        });
+      }
+    }
+  });
+
+const leafNodeSchema = z.union([
+  z.object({ type: z.literal('heading'), text: z.string().max(120) }),
+  z.object({
+    type: z.literal('text'),
+    value: z.string().max(5000),
+    muted: z.boolean().default(false),
+  }),
+  /** Rendered by core's sanitizing markdown renderer — never raw HTML. */
+  z.object({ type: z.literal('markdown'), value: z.string().max(20000) }),
+  z.object({
+    type: z.literal('stat'),
+    label: z.string().max(80),
+    value: z.string().max(40),
+    hint: z.string().max(120).optional(),
+  }),
+  buttonSchema,
+  z.object({
+    type: z.literal('form'),
+    key: slug,
+    fields: z
+      .array(
+        z.object({
+          kind: z.enum(['text', 'textarea', 'select']),
+          name: slug,
+          label: z.string().max(80),
+          value: z.string().max(20000).optional(),
+          options: z.array(z.object({ value: z.string(), label: z.string() })).optional(),
+          required: z.boolean().default(false),
+        }),
+      )
+      .max(30),
+    /** Field values are posted as the action's `input`, keyed by field name. */
+    submit: z.object({ label: z.string().max(80), action: slug }),
+  }),
+  z.object({
+    type: z.literal('table'),
+    columns: z.array(z.object({ key: slug, label: z.string().max(80) })).max(12),
+    rows: z
+      .array(
+        z.object({
+          key: z.string().max(128),
+          cells: z.record(slug, cellSchema),
+          onPress: pressSchema.optional(),
+        }),
+      )
+      .max(500),
+    /** Shown when `rows` is empty — every data-bound surface needs an empty state. */
+    empty: z.string().max(200),
+  }),
+  z.object({
+    type: z.literal('timeline'),
+    items: z
+      .array(
+        z.object({
+          label: z.string().max(200),
+          status: z.enum(['pending', 'active', 'done', 'error']),
+          at: z.iso.datetime().optional(),
+          detail: z.string().max(1000).optional(),
+        }),
+      )
+      .max(200),
+  }),
+  /**
+   * A HITL approval slot — a REFERENCE, never content. The module places the
+   * request id where the card should appear; core resolves it at render time
+   * (tenant + this-install + still-pending checks) and renders the platform
+   * card wired to the respond endpoint. The module cannot author the card
+   * (a forged prompt/options here is ignored — this node carries no fields
+   * for them) and the tree transports no PHI, only the opaque id.
+   */
+  z.object({ type: z.literal('pending_request'), requestId: z.string().min(1).max(128) }),
+  /**
+   * The zero-bookkeeping HITL slot: "render ALL of this module's still-pending
+   * approvals here." Core fills it from its own pending store — the module
+   * needs no request-id tracking (which the id-form above requires). Requests
+   * already placed individually via `pending_request` elsewhere in the same
+   * tree are not repeated here.
+   */
+  z.object({ type: z.literal('pending_requests') }),
+  choiceCardsSchema,
+  progressSchema,
+  chartSchema,
+]);
+
+type LeafScreenNode = z.infer<typeof leafNodeSchema>;
+type LeafScreenNodeInput = z.input<typeof leafNodeSchema>;
+
+export type ScreenNode =
+  | LeafScreenNode
+  | {
+      type: 'section';
+      title?: string;
+      description?: string;
+      layout: 'stack' | 'grid';
+      columns: number;
+      children: ScreenNode[];
+    };
+
+type ScreenNodeInput =
+  | LeafScreenNodeInput
+  | {
+      type: 'section';
+      title?: string;
+      description?: string;
+      layout: 'stack' | 'grid';
+      columns: number;
+      children: ScreenNodeInput[];
+    };
+
+const MAX_SECTION_DEPTH = 8;
+const nodeSchemas = new Map<number, z.ZodType<ScreenNode, ScreenNodeInput>>();
+
+function nodeSchemaAtDepth(depth: number): z.ZodType<ScreenNode, ScreenNodeInput> {
+  const cached = nodeSchemas.get(depth);
+  if (cached) return cached;
+  if (depth === MAX_SECTION_DEPTH) return leafNodeSchema;
+
+  const schema: z.ZodType<ScreenNode, ScreenNodeInput> = z.union([
+    leafNodeSchema,
+    z.object({
+      type: z.literal('section'),
+      title: z.string().max(120).optional(),
+      description: z.string().max(300).optional(),
+      layout: z.enum(['stack', 'grid']),
+      columns: z.number().int().min(1).max(4),
+      children: z.array(z.lazy(() => nodeSchemaAtDepth(depth + 1))).max(100),
+    }),
+  ]);
+  nodeSchemas.set(depth, schema);
+  return schema;
+}
+
+export const nodeSchema = nodeSchemaAtDepth(0);
+
+export const screenTreeSchema = z.object({
+  version: z.literal(UI_SCHEMA_VERSION),
+  title: z.string().max(120),
+  description: z.string().max(300).optional(),
+  /** Page-level actions, rendered in the header (e.g. "New draft"). */
+  actions: z.array(buttonSchema).max(4).optional(),
+  children: z.array(nodeSchema).max(100),
+  // ponytail: polling keeps live views (agent activity) simple; switch to the
+  // existing run-event NDJSON stream when polling measurably falls short.
+  refreshSeconds: z.number().int().min(2).max(300).optional(),
+});
+
+/** What an action handler returns. `refresh` re-runs `load` after the action. */
+export const actionResultSchema = z.object({
+  toast: z.string().max(200).optional(),
+  navigate: z
+    .object({ screen: slug, params: z.record(z.string(), z.string()).optional() })
+    .optional(),
+  refresh: z.boolean().default(true),
+});
+
+/* --------------------------------------------------------------------- */
+/* Wire protocol: core proxy <-> module runtime (grant in Authorization).  */
+/* eve runtimes serve these from agent/channels/screens.ts (custom channel */
+/* routes mount at the runtime root):                                      */
+/*   POST {runtime}/screens/{screen}/load             -> ScreenLoadResponse */
+/*   POST {runtime}/screens/{screen}/actions/{action} -> ActionResult       */
+/* --------------------------------------------------------------------- */
+
+export const screenLoadRequestSchema = z.object({
+  params: z.record(z.string(), z.string()).default({}),
+});
+
+export const screenLoadResponseSchema = z.object({ tree: screenTreeSchema });
+
+export const screenActionRequestSchema = z.object({
+  params: z.record(z.string(), z.string()).default({}),
+  input: z.record(z.string(), z.unknown()).default({}),
+  /** Core-generated, forwarded so the handler can be idempotent on retries too
+   *  (core already dedupes via command_log; this is the belt-and-suspenders
+   *  half of at-least-once). Optional for runtime version-skew tolerance. */
+  idempotencyKey: z.string().max(200).optional(),
+});
+
+/**
+ * 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({
+  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 type Press = z.infer<typeof pressSchema>;
+export type ScreenTree = z.infer<typeof screenTreeSchema>;
+export type ActionResult = z.infer<typeof actionResultSchema>;
+export type Surface = z.infer<typeof surfaceSchema>;
+
+// Authoring-side types: fields with schema defaults (variant, muted, required,
+// refresh…) are optional here; core's parse() fills them in. Handlers return
+// these; renderers consume the parsed output types above.
+export type ScreenTreeInput = z.input<typeof screenTreeSchema>;
+export type ActionResultInput = z.input<typeof actionResultSchema>;