@keemakr/ui-sdk 1.4.0-dev-20261012081437 → 1.4.0-dev-20261012082811

package/README.md

@@ -54,7 +54,50 @@ export default defineScreen({
 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
+## 4. Optional workspace presentation
+
+Screens use the document layout unless they opt into a platform-owned workspace. A workspace can
+place page actions in a pinned footer and promote one keyed root section into a responsive right
+rail. The module declares meaning; each Keemakr client owns widths, breakpoints and styling.
+
+```ts
+load: async () => ({
+  version: 1,
+  title: 'Account review',
+  actions: [
+    {
+      type: 'button',
+      label: 'Save review',
+      onPress: { kind: 'action', action: 'save_review' },
+    },
+  ],
+  presentation: {
+    layout: 'workspace',
+    actionPlacement: 'footer',
+    rightRail: {
+      sectionKey: 'history',
+      label: 'Review history',
+      collapsible: true,
+    },
+  },
+  children: [
+    { type: 'text', value: 'Current review' },
+    {
+      type: 'section',
+      key: 'history',
+      title: 'History',
+      layout: 'stack',
+      columns: 1,
+      children: [{ type: 'text', value: 'Version 1' }],
+    },
+  ],
+}),
+```
+
+`rightRail.sectionKey` must identify exactly one keyed section in the screen's root `children`.
+Older screens require no changes and keep header actions plus the normal document flow.
+
+## 5. Generate before Eve runs
 
 Use the SDK wrapper in the module scripts:
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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, ScreenRootNode, ScreenTree, ActionResult, InterfaceFamily, SurfaceDefinition, Surface, ScreenRegistration, UiManifest, ScreenTreeInput, ActionResultInput, } from './schema.js';
+export { UI_SCHEMA_VERSION, pressSchema, buttonSchema, cellSchema, nodeSchema, screenPresentationSchema, screenTreeSchema, actionResultSchema, screenLoadRequestSchema, screenLoadResponseSchema, screenActionRequestSchema, interfaceFamilySchema, surfaceDefinitionSchema, surfaceSchema, screenRegistrationSchema, uiManifestSchema, } from './schema.js';
+export type { Press, ScreenPresentation, ScreenNode, ScreenRootNode, ScreenTree, ActionResult, InterfaceFamily, SurfaceDefinition, Surface, ScreenRegistration, UiManifest, ScreenTreeInput, ActionResultInput, } from './schema.js';
 export { childNodesOf, KNOWN_CONTAINERS, KNOWN_NODE_TYPES } from './nodes.js';
 export type { ContainerChild, ContainerNodeType, KnownNodeType } from './nodes.js';
 export { pageRangeLabel, pageWindow, pressWithValue } from './pager.js';

package/dist/index.js

@@ -6,7 +6,7 @@
 //                    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, interfaceFamilySchema, surfaceDefinitionSchema, surfaceSchema, screenRegistrationSchema, uiManifestSchema, } from './schema.js';
+export { UI_SCHEMA_VERSION, pressSchema, buttonSchema, cellSchema, nodeSchema, screenPresentationSchema, screenTreeSchema, actionResultSchema, screenLoadRequestSchema, screenLoadResponseSchema, screenActionRequestSchema, interfaceFamilySchema, surfaceDefinitionSchema, surfaceSchema, screenRegistrationSchema, uiManifestSchema, } from './schema.js';
 export { childNodesOf, KNOWN_CONTAINERS, KNOWN_NODE_TYPES } from './nodes.js';
 export { pageRangeLabel, pageWindow, pressWithValue } from './pager.js';
 export { defineScreen, defineSurface } from './define.js';

package/dist/nodes.d.ts

@@ -1,6 +1,6 @@
 import type { ScreenRootNode } from './schema.js';
 /** Every node type the root union admits (KEE-574 item 3). */
-export declare const KNOWN_NODE_TYPES: readonly ["heading", "text", "markdown", "stat", "button", "form", "table", "timeline", "pending_request", "pending_requests", "choice_cards", "progress", "chart", "pagination", "select", "alert", "details", "timestamp", "divider", "section", "tabs"];
+export declare const KNOWN_NODE_TYPES: readonly ["heading", "text", "markdown", "stat", "button", "form", "table", "timeline", "pending_request", "pending_requests", "choice_cards", "progress", "chart", "pagination", "select", "alert", "details", "timestamp", "divider", "board", "section", "tabs"];
 export type KnownNodeType = (typeof KNOWN_NODE_TYPES)[number];
 /**
  * The node types that hold child nodes. `section` mounts its children

package/dist/nodes.js

@@ -29,6 +29,7 @@ export const KNOWN_NODE_TYPES = [
     'details',
     'timestamp',
     'divider',
+    'board',
     'section',
     'tabs',
 ];

package/dist/schema.d.ts

@@ -365,11 +365,56 @@ declare const leafNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"divider">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"board">;
+    columns: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        tone: z.ZodDefault<z.ZodEnum<{
+            success: "success";
+            default: "default";
+            warning: "warning";
+            destructive: "destructive";
+        }>>;
+        cards: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            title: z.ZodString;
+            subtitle: z.ZodOptional<z.ZodString>;
+            values: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"text">;
+                value: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"badge">;
+                value: z.ZodString;
+                tone: z.ZodDefault<z.ZodEnum<{
+                    success: "success";
+                    default: "default";
+                    warning: "warning";
+                    destructive: "destructive";
+                }>>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"date">;
+                value: z.ZodISODateTime;
+            }, z.core.$strip>], "kind">>>;
+            onPress: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"action">;
+                action: z.ZodString;
+                input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                confirm: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"navigate">;
+                screen: z.ZodString;
+                params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            }, z.core.$strip>], "kind">>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    empty: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>], "type">;
 type LeafScreenNode = z.infer<typeof leafNodeSchema>;
 type LeafScreenNodeInput = z.input<typeof leafNodeSchema>;
 export type ScreenNode = LeafScreenNode | {
     type: 'section';
+    key?: string;
     title?: string;
     description?: string;
     layout: 'stack' | 'grid' | 'row';
@@ -379,6 +424,7 @@ export type ScreenNode = LeafScreenNode | {
 };
 type ScreenNodeInput = LeafScreenNodeInput | {
     type: 'section';
+    key?: string;
     title?: string;
     description?: string;
     layout: 'stack' | 'grid' | 'row';
@@ -424,6 +470,19 @@ type ScreenRootNodeInput = ScreenNodeInput | TabsScreenNodeInput;
  * MAX_SECTION_DEPTH exactly as it was before `tabs` existed.
  */
 export declare const nodeSchema: z.ZodType<ScreenRootNode, ScreenRootNodeInput>;
+export declare const screenPresentationSchema: z.ZodObject<{
+    layout: z.ZodLiteral<"workspace">;
+    actionPlacement: z.ZodDefault<z.ZodEnum<{
+        header: "header";
+        footer: "footer";
+    }>>;
+    rightRail: z.ZodOptional<z.ZodObject<{
+        sectionKey: z.ZodString;
+        label: z.ZodString;
+        collapsible: z.ZodDefault<z.ZodBoolean>;
+        defaultCollapsed: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export declare const screenTreeSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     title: z.ZodString;
@@ -459,6 +518,19 @@ export declare const screenTreeSchema: z.ZodObject<{
         disabledReason: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     children: z.ZodArray<z.ZodType<ScreenRootNode, ScreenRootNodeInput, z.core.$ZodTypeInternals<ScreenRootNode, ScreenRootNodeInput>>>;
+    presentation: z.ZodOptional<z.ZodObject<{
+        layout: z.ZodLiteral<"workspace">;
+        actionPlacement: z.ZodDefault<z.ZodEnum<{
+            header: "header";
+            footer: "footer";
+        }>>;
+        rightRail: z.ZodOptional<z.ZodObject<{
+            sectionKey: z.ZodString;
+            label: z.ZodString;
+            collapsible: z.ZodDefault<z.ZodBoolean>;
+            defaultCollapsed: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
     refreshSeconds: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 /** What an action handler returns. `refresh` re-runs `load` after the action. */
@@ -509,6 +581,19 @@ export declare const screenLoadResponseSchema: z.ZodObject<{
             disabledReason: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
         children: z.ZodArray<z.ZodType<ScreenRootNode, ScreenRootNodeInput, z.core.$ZodTypeInternals<ScreenRootNode, ScreenRootNodeInput>>>;
+        presentation: z.ZodOptional<z.ZodObject<{
+            layout: z.ZodLiteral<"workspace">;
+            actionPlacement: z.ZodDefault<z.ZodEnum<{
+                header: "header";
+                footer: "footer";
+            }>>;
+            rightRail: z.ZodOptional<z.ZodObject<{
+                sectionKey: z.ZodString;
+                label: z.ZodString;
+                collapsible: z.ZodDefault<z.ZodBoolean>;
+                defaultCollapsed: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
         refreshSeconds: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;
 }, z.core.$strip>;
@@ -569,6 +654,7 @@ export declare const uiManifestSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type Press = z.infer<typeof pressSchema>;
+export type ScreenPresentation = z.infer<typeof screenPresentationSchema>;
 export type ScreenTree = z.infer<typeof screenTreeSchema>;
 export type ActionResult = z.infer<typeof actionResultSchema>;
 export type InterfaceFamily = z.infer<typeof interfaceFamilySchema>;

package/dist/schema.js

@@ -233,6 +233,71 @@ const timestampSchema = z.object({
     /** Shown before the time, muted: "Last contacted". */
     label: z.string().max(80).optional(),
 });
+/**
+ * Cards in columns by stage: a sales pipeline, installs by status, accounts by
+ * health. A card carries a title, an optional subtitle, and up to 3 values that
+ * reuse the table cell kinds (a `date` shows in the viewer's zone, a `badge`
+ * keeps its tone). A card with `onPress` opens a record or calls an action.
+ * Each column shows its card count. Moving a card between columns is not part
+ * of this block yet: call an action from the record instead.
+ */
+const boardSchema = z
+    .object({
+    type: z.literal('board'),
+    columns: z
+        .array(z.object({
+        key: slug,
+        label: z.string().min(1).max(40),
+        /** Colours the column's count: an at-risk stage, a done stage. */
+        tone: tone.default('default'),
+        cards: z
+            .array(z.object({
+            key: z.string().min(1).max(128),
+            title: z.string().min(1).max(120),
+            subtitle: z.string().max(200).optional(),
+            values: z.array(cellSchema).max(3).optional(),
+            onPress: pressSchema.optional(),
+        }))
+            .max(100),
+    }))
+        .min(1)
+        .max(8),
+    /** Shown in a column that has no cards. */
+    empty: z.string().min(1).max(80).default('Nothing here'),
+})
+    .superRefine((node, ctx) => {
+    const columnKeys = new Set();
+    const cardKeys = new Set();
+    let cards = 0;
+    for (const [c, column] of node.columns.entries()) {
+        if (columnKeys.has(column.key)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['columns', c, 'key'],
+                message: `duplicate column key "${column.key}"`,
+            });
+        }
+        columnKeys.add(column.key);
+        for (const [i, card] of column.cards.entries()) {
+            if (cardKeys.has(card.key)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: ['columns', c, 'cards', i, 'key'],
+                    message: `duplicate card key "${card.key}"`,
+                });
+            }
+            cardKeys.add(card.key);
+        }
+        cards += column.cards.length;
+    }
+    if (cards > 500) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['columns'],
+            message: `a board holds at most 500 cards, got ${cards}`,
+        });
+    }
+});
 /**
  * A horizontal line that says where one part of a screen ends and the next
  * begins. It carries no content. Use a `section` when the parts need a title.
@@ -362,12 +427,15 @@ const leafNodeSchema = z.discriminatedUnion('type', [
     detailsSchema,
     timestampSchema,
     dividerSchema,
+    boardSchema,
 ]);
 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'),
+    /** Stable identity for presentation regions that reference this root section. */
+    key: slug.optional(),
     title: z.string().max(120).optional(),
     description: z.string().max(300).optional(),
     /**
@@ -448,7 +516,26 @@ export const nodeSchema = z.discriminatedUnion('type', [
     sectionBranch(z.lazy(() => nodeSchemaAtDepth(1))),
     tabsBranch(z.lazy(() => nodeSchemaAtDepth(1))),
 ]);
-export const screenTreeSchema = z.object({
+export const screenPresentationSchema = z.object({
+    /** A full-height working surface whose chrome stays outside its content scroller. */
+    layout: z.literal('workspace'),
+    /** Where the renderer places the screen's page-level actions. */
+    actionPlacement: z.enum(['header', 'footer']).default('header'),
+    /**
+     * Promote one keyed root section into a supporting right rail. Renderers own
+     * its responsive width and visual treatment; modules only declare meaning.
+     */
+    rightRail: z
+        .object({
+        sectionKey: slug,
+        label: z.string().min(1).max(80),
+        collapsible: z.boolean().default(false),
+        defaultCollapsed: z.boolean().default(false),
+    })
+        .optional(),
+});
+export const screenTreeSchema = z
+    .object({
     version: z.literal(UI_SCHEMA_VERSION),
     title: z.string().max(120),
     description: z.string().max(300).optional(),
@@ -471,12 +558,34 @@ export const screenTreeSchema = z.object({
         .min(1)
         .max(5)
         .optional(),
-    /** Page-level actions, rendered in the header (e.g. "New draft"). */
+    /** Page-level actions. Presentation chooses header or pinned workspace footer. */
     actions: z.array(buttonSchema).max(4).optional(),
     children: z.array(nodeSchema).max(100),
+    /** Optional platform-owned layout semantics. Absence preserves the document layout. */
+    presentation: screenPresentationSchema.optional(),
     // 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(),
+})
+    .superRefine((tree, ctx) => {
+    const rail = tree.presentation?.rightRail;
+    if (!rail)
+        return;
+    if (rail.defaultCollapsed && !rail.collapsible) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['presentation', 'rightRail', 'defaultCollapsed'],
+            message: 'requires collapsible to be true',
+        });
+    }
+    const matches = tree.children.filter((node) => node.type === 'section' && node.key === rail.sectionKey);
+    if (matches.length !== 1) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['presentation', 'rightRail', 'sectionKey'],
+            message: 'must identify exactly one keyed root section',
+        });
+    }
 });
 /** What an action handler returns. `refresh` re-runs `load` after the action. */
 export const actionResultSchema = z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keemakr/ui-sdk",
-  "version": "1.4.0-dev-20261012081437",
+  "version": "1.4.0-dev-20261012082811",
   "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",