@keemakr/ui-sdk 1.5.0 → 1.6.0-dev-20261026112734

package/dist/published/v1.1.0/schema.js

@@ -0,0 +1,405 @@
+// FROZEN COPY of the published @keemakr/ui-sdk@1.1.0 src/schema.ts (git tag @keemakr/ui-sdk@1.1.0).
+// Core checks the tree it sends an older app against the schema that app really parses with.
+// Do not edit: tests/sdk/ui-published-parsers.test.ts pins the bytes below this header.
+/**
+ * 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) {
+        const series = chart.series[i];
+        if (series && series.values.length !== chart.categories.length) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['series', i, 'values'],
+                message: 'must contain one value per category',
+            });
+        }
+    }
+});
+const headingSchema = z.object({ type: z.literal('heading'), text: z.string().max(120) });
+const textSchema = 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. */
+const markdownSchema = z.object({ type: z.literal('markdown'), value: z.string().max(20000) });
+const statSchema = z.object({
+    type: z.literal('stat'),
+    label: z.string().max(80),
+    value: z.string().max(40),
+    hint: z.string().max(120).optional(),
+});
+/**
+ * What a table row may reveal in place. Deliberately NOT the leaf union and NOT
+ * `nodeSchema`: `table` is itself a leaf, so either reference re-opens the
+ * recursion — both were measured accepting a 200-level `table -> expand -> table`
+ * chain, escaping MAX_SECTION_DEPTH entirely, and both collapsed type inference
+ * (TS7022 on the leaf union, TS7024 on the lazy callback). Naming the five
+ * content branches explicitly keeps this non-recursive by construction, which is
+ * why the depth test asserts REJECTION rather than slowness: the validator
+ * handles 200 levels in tens of milliseconds, so nothing upstream would catch it.
+ *
+ * The general rule: any leaf that references the leaf union re-opens the recursion.
+ */
+const expandContentSchema = z.discriminatedUnion('type', [
+    headingSchema,
+    textSchema,
+    markdownSchema,
+    statSchema,
+    buttonSchema,
+]);
+const leafNodeSchema = z.discriminatedUnion('type', [
+    headingSchema,
+    textSchema,
+    markdownSchema,
+    statSchema,
+    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(),
+            /**
+             * Content the row reveals in place, no navigation hop. Content nodes
+             * only — no nested `table`, no `section`.
+             *
+             * A row declaring `expand` WITH CONTENT toggles disclosure when
+             * activated, and its `onPress` is IGNORED. The renderer already gives a
+             * pressable row `role="button"` with an Enter/Space handler, so a second
+             * focusable control inside it would be invalid ARIA with two handlers on
+             * one key. Expansion is local view state; a press means "call my
+             * runtime". They stay apart deliberately.
+             *
+             * Zero children is allowed and means NO disclosure — the row behaves
+             * exactly as if `expand` were absent, `onPress` included. A body built
+             * from data legitimately drops to nothing, and rejecting that would fail
+             * the whole screen load rather than degrade one row (the same cliff the
+             * tab strip's minimum had). The maximum stays: an oversize body has no
+             * safe degradation — truncating it would be silent data loss.
+             */
+            expand: z.object({ children: z.array(expandContentSchema).max(20) }).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,
+]);
+const MAX_SECTION_DEPTH = 8;
+const nodeSchemas = new Map();
+/** Shared by the chain and by the root union, so the two cannot drift apart. */
+const sectionBranch = (children) => 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(children).max(100),
+});
+const tabsBranch = (children) => z
+    .object({
+    type: z.literal('tabs'),
+    key: slug,
+    /** A hint only — the renderer owns selection, and it survives no reload. */
+    active: slug.optional(),
+    // One tab is legitimate: a strip generated per live queue drops to one when
+    // only one queue exists, and rejecting that fails the WHOLE screen load.
+    tabs: z
+        .array(z.object({
+        key: slug,
+        label: z.string().min(1).max(40),
+        /** Sits beside the label — a count, not prose. */
+        badge: z.string().max(12).optional(),
+        children: z.array(children).max(100),
+    }))
+        .min(1)
+        .max(6),
+})
+    .superRefine((node, ctx) => {
+    const keys = new Set();
+    for (const [index, tab] of node.tabs.entries()) {
+        if (keys.has(tab.key)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['tabs', index, 'key'],
+                message: `duplicate tab key "${tab.key}"`,
+            });
+        }
+        keys.add(tab.key);
+    }
+    if (node.active !== undefined && !keys.has(node.active)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['active'],
+            message: `active tab "${node.active}" is not one of the declared tabs`,
+        });
+    }
+});
+function nodeSchemaAtDepth(depth) {
+    const cached = nodeSchemas.get(depth);
+    if (cached)
+        return cached;
+    if (depth === MAX_SECTION_DEPTH)
+        return leafNodeSchema;
+    const schema = z.discriminatedUnion('type', [
+        leafNodeSchema,
+        sectionBranch(z.lazy(() => nodeSchemaAtDepth(depth + 1))),
+    ]);
+    nodeSchemas.set(depth, schema);
+    return schema;
+}
+/**
+ * The root union: the chain's own membership plus `tabs`. Both container
+ * branches descend into the chain at depth 1, so nesting stays bounded by
+ * MAX_SECTION_DEPTH exactly as it was before `tabs` existed.
+ */
+export const nodeSchema = z.discriminatedUnion('type', [
+    leafNodeSchema,
+    sectionBranch(z.lazy(() => nodeSchemaAtDepth(1))),
+    tabsBranch(z.lazy(() => nodeSchemaAtDepth(1))),
+]);
+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(),
+});
+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 = surfaceDefinitionSchema.extend({
+    key: slug,
+    screen: slug,
+});
+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/dist/published/v1.4.0/dataset-view.d.ts

@@ -0,0 +1,160 @@
+/**
+ * The `dataset` node, and how a dataset becomes blocks.
+ *
+ * A screen places one of its module's datasets with a single node:
+ *
+ *   { type: 'dataset', dataset: 'leads', layout: 'table' }
+ *
+ * Core expands the node before any renderer sees it: it queries the dataset
+ * with the viewer's grant and replaces the node with blocks every app already
+ * draws. So a new layout never needs a new client. The layouts:
+ *
+ * - `table`: a table with sort and filter headers and a pager.
+ * - `board`: cards in columns, grouped by a stage or a status.
+ * - `list`: a table with filter chips over its stage or status. Pressing a
+ *   row opens it as a record beside the list, in the screen's right rail.
+ * - `record`: one row, named by a screen param, as a page: its title, its
+ *   status, and its other fields as facts. This file is the pure
+ * half of that: the node's schema, how a screen's params become a query, and
+ * how one page of rows becomes blocks. It runs on the server and in tests.
+ *
+ * Interaction is navigation. A sort header, a filter menu and the pager each
+ * navigate back to the same screen with params (`sort`, `direction`, a field
+ * name, the page param), and the next expansion reads them. One interactive
+ * dataset node per screen: two would share those param names.
+ */
+import { z } from 'zod';
+import { type DatasetDeclaration, type DatasetField, type DatasetQueryRequestInput, type DatasetQueryResponse, type DatasetRow } from './dataset.js';
+export declare const DATASET_LAYOUTS: readonly ["table", "board", "list", "record", "chart"];
+export type DatasetLayout = (typeof DATASET_LAYOUTS)[number];
+/** Deepest page a table reaches. Paging walks cursors from page 1. */
+export declare const DATASET_MAX_PAGE = 20;
+export declare const datasetNodeSchema: z.ZodObject<{
+    type: z.ZodLiteral<"dataset">;
+    dataset: z.ZodString;
+    layout: z.ZodDefault<z.ZodEnum<{
+        record: "record";
+        table: "table";
+        board: "board";
+        list: "list";
+        chart: "chart";
+    }>>;
+    fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    sort: z.ZodOptional<z.ZodObject<{
+        field: z.ZodString;
+        direction: z.ZodDefault<z.ZodEnum<{
+            asc: "asc";
+            desc: "desc";
+        }>>;
+    }, z.core.$strip>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    groupBy: z.ZodOptional<z.ZodString>;
+    chart: z.ZodOptional<z.ZodObject<{
+        form: z.ZodDefault<z.ZodEnum<{
+            bars: "bars";
+            funnel: "funnel";
+        }>>;
+        measure: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    open: z.ZodOptional<z.ZodObject<{
+        screen: z.ZodString;
+        param: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    param: z.ZodDefault<z.ZodString>;
+    empty: z.ZodDefault<z.ZodString>;
+    create: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type DatasetNode = z.infer<typeof datasetNodeSchema>;
+export type DatasetNodeInput = z.input<typeof datasetNodeSchema>;
+/** The screen a dataset node sits on: where its presses navigate back to. */
+export interface DatasetScreenContext {
+    screen: string;
+    params: Record<string, string>;
+}
+/** Problems with a node against its dataset. Core shows these, never a broken view. */
+export declare function datasetNodeIssues(node: DatasetNode, declaration: DatasetDeclaration): string[];
+/** Which page of a table the params ask for, 1 when none. */
+export declare function datasetPage(node: DatasetNode, params: Record<string, string>): number;
+/**
+ * The key of the row a record shows, or a list opens beside it. Undefined when
+ * the node shows no single row, or the param is empty.
+ */
+export declare function datasetRecordKey(node: DatasetNode, params: Record<string, string>): string | undefined;
+/** The query for the one row a record shows. */
+export declare function datasetRecordQuery(key: string): DatasetQueryRequestInput;
+/**
+ * The query a node and the screen's params make. The node's own filters win
+ * over a param of the same name; a param for a field the dataset does not let
+ * a person filter is ignored, never forwarded.
+ */
+export declare function datasetQueryFor(node: DatasetNode, declaration: DatasetDeclaration, params: Record<string, string>): DatasetQueryRequestInput;
+type Cell = {
+    kind: 'text';
+    value: string;
+} | {
+    kind: 'badge';
+    value: string;
+    tone: 'default' | 'success' | 'warning' | 'destructive';
+} | {
+    kind: 'date';
+    value: string;
+};
+/** One value as a table cell, or null when the row has none. */
+export declare function datasetCell(field: DatasetField, value: DatasetRow[string]): Cell | null;
+/**
+ * One row as a record: its title, its subtitle, a tag for its status and its
+ * stage, and its other fields as facts. `row` undefined means the module did
+ * not find the key, and the record says so.
+ */
+export declare function compileDatasetRecord(opts: {
+    declaration: DatasetDeclaration;
+    row: DatasetRow | undefined;
+}): Record<string, unknown>[];
+/** The key of the root section that holds the record a list opened. */
+export declare const DATASET_RECORD_SECTION = "dataset-record";
+/**
+ * The record a list opened, as the section the screen's right rail shows,
+ * with a button that closes it.
+ */
+export declare function compileDatasetRecordPanel(opts: {
+    node: DatasetNode;
+    declaration: DatasetDeclaration;
+    row: DatasetRow | undefined;
+    screen: DatasetScreenContext;
+}): Record<string, unknown>;
+/**
+ * One page of rows as screen blocks. `rows` is the page to show; `total` and
+ * `hasMore` drive the pager. The output is plain screen nodes, ready to put in
+ * the node's place.
+ */
+export declare function compileDatasetNode(opts: {
+    node: DatasetNode;
+    declaration: DatasetDeclaration;
+    response: DatasetQueryResponse;
+    screen: DatasetScreenContext;
+    page: number;
+    hasMore: boolean;
+}): Record<string, unknown>[];
+/**
+ * The screen param that opens a dataset's create form: its value is the
+ * dataset's name. Reserved on every screen that shows a dataset.
+ */
+export declare const DATASET_NEW_PARAM = "new";
+/**
+ * The action a create form submits. Core answers it itself: it checks the input
+ * against the declaration and calls the module's `create`. A module never
+ * receives it, so no module screen may name an action this.
+ */
+export declare const DATASET_CREATE_ACTION = "kee-dataset-create";
+/**
+ * The create affordance for a dataset node: a button that opens the form, or,
+ * once the `new` param names this dataset, the form itself with Cancel. Empty
+ * when the dataset takes no new rows, the node turns it off, or it is a record.
+ */
+export declare function compileDatasetCreate(opts: {
+    node: DatasetNode;
+    declaration: DatasetDeclaration;
+    screen: DatasetScreenContext;
+}): Record<string, unknown>[];
+export {};