agentic-zi-ui-schema 0.0.1

package/src/index.ts

@@ -0,0 +1,543 @@
+import { z } from "zod";
+
+/**
+ * ui.v1 — a safe, declarative UI schema.
+ * - No executable JS
+ * - Events map to action descriptors
+ * - Client uses allowlists to render
+ */
+
+// ------------------ Guardrails ------------------
+
+export const UI_LIMITS = {
+  MAX_NODES: 500,
+  MAX_DEPTH: 30,
+  MAX_TEXT_LEN: 10_000,
+  MAX_CLASSNAME_LEN: 1_000,
+  MAX_ID_LEN: 200,
+  MAX_URL_LEN: 2_000,
+  MAX_KEY_LEN: 200,
+} as const;
+
+export const UI_ALLOWED_TAGS = [
+  "a",
+  "article",
+  "aside",
+  "blockquote",
+  "br",
+  "button",
+  "code",
+  "div",
+  "em",
+  "figcaption",
+  "figure",
+  "fieldset",
+  "footer",
+  "form",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "header",
+  "hr",
+  "img",
+  "input",
+  "label",
+  "li",
+  "main",
+  "nav",
+  "ol",
+  "option",
+  "p",
+  "path",
+  "pre",
+  "section",
+  "select",
+  "small",
+  "span",
+  "strong",
+  "svg",
+  "table",
+  "tbody",
+  "td",
+  "textarea",
+  "tfoot",
+  "th",
+  "thead",
+  "tr",
+  "ul",
+] as const;
+
+export const UI_ALLOWED_PROPS = [
+  "alt",
+  "aria-label",
+  "aria-controls",
+  "aria-current",
+  "aria-describedby",
+  "aria-disabled",
+  "aria-expanded",
+  "aria-hidden",
+  "aria-invalid",
+  "aria-labelledby",
+  "aria-live",
+  "aria-pressed",
+  "aria-required",
+  "aria-selected",
+  "aria-checked",
+  "aria-valuemax",
+  "aria-valuemin",
+  "aria-valuenow",
+  "aria-valuetext",
+  "aria-busy",
+  "checked",
+  "clipRule",
+  "cols",
+  "cx",
+  "cy",
+  "d",
+  "decoding",
+  "disabled",
+  "fill",
+  "fillRule",
+  "height",
+  "htmlFor",
+  "href",
+  "loading",
+  "max",
+  "maxLength",
+  "min",
+  "minLength",
+  "name",
+  "opacity",
+  "placeholder",
+  "preserveAspectRatio",
+  "rel",
+  "role",
+  "r",
+  "rows",
+  "src",
+  "stroke",
+  "strokeLinecap",
+  "strokeLinejoin",
+  "strokeWidth",
+  "step",
+  "target",
+  "title",
+  "type",
+  "value",
+  "viewBox",
+  "width",
+  "x",
+  "y",
+] as const;
+
+export const UI_ALLOWED_EVENTS = [
+  "onClick",
+  "onChange",
+  "onSubmit",
+  "onMouseEnter",
+  "onMouseLeave",
+  "onMouseOver",
+  "onMouseOut",
+  "onMouseDown",
+  "onMouseUp",
+  "onMouseMove",
+  "onFocus",
+  "onBlur",
+] as const;
+
+const zSafeId = z.string().min(1).max(UI_LIMITS.MAX_ID_LEN);
+const zSafeText = z.string().max(UI_LIMITS.MAX_TEXT_LEN);
+const zSafeClassName = z.string().max(UI_LIMITS.MAX_CLASSNAME_LEN);
+const zSafeKey = z.string().min(1).max(UI_LIMITS.MAX_KEY_LEN);
+const zSafePropValue = z.union([z.string(), z.number(), z.boolean()]);
+
+const UI_BASE_PROP_KEYS = new Set<string>(UI_ALLOWED_PROPS);
+
+// ------------------ Actions ------------------
+
+export const UiActionTypeSchema = z.enum([
+  "FLOW_EVENT",
+  "OPEN_URL",
+  "COPY",
+  "TOAST",
+  "PATCH_STATE",
+]);
+
+export type UiActionType = z.infer<typeof UiActionTypeSchema>;
+
+export const UiActionSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("FLOW_EVENT"),
+    name: z.string().min(1).max(200),
+    payload: z.record(z.string(), z.unknown()).optional(),
+  }),
+  z.object({
+    type: z.literal("OPEN_URL"),
+    url: z.string().min(1).max(UI_LIMITS.MAX_URL_LEN),
+    target: z.enum(["_blank", "_self"]).optional(),
+  }),
+  z.object({
+    type: z.literal("COPY"),
+    text: zSafeText,
+  }),
+  z.object({
+    type: z.literal("TOAST"),
+    message: z.string().min(1).max(500),
+    level: z.enum(["info", "success", "warning", "error"]).optional(),
+  }),
+  z.object({
+    // Local component state patch. (POC: flat key/value)
+    type: z.literal("PATCH_STATE"),
+    key: z.string().min(1).max(UI_LIMITS.MAX_KEY_LEN),
+    valueFrom: z
+      .enum(["event.target.value", "event.target.checked"])
+      .optional(),
+    value: z.unknown().optional(),
+  }),
+]);
+
+export type UiAction = z.infer<typeof UiActionSchema>;
+
+// ------------------ Events ------------------
+
+export const UiEventMapSchema = z
+  .object({
+    onClick: UiActionSchema.optional(),
+    onChange: UiActionSchema.optional(),
+    onSubmit: UiActionSchema.optional(),
+    onMouseEnter: UiActionSchema.optional(),
+    onMouseLeave: UiActionSchema.optional(),
+    onMouseOver: UiActionSchema.optional(),
+    onMouseOut: UiActionSchema.optional(),
+    onMouseDown: UiActionSchema.optional(),
+    onMouseUp: UiActionSchema.optional(),
+    onMouseMove: UiActionSchema.optional(),
+    onFocus: UiActionSchema.optional(),
+    onBlur: UiActionSchema.optional(),
+  })
+  .strict();
+
+export type UiEventMap = z.infer<typeof UiEventMapSchema>;
+
+// ------------------ Node schema ------------------
+
+/**
+ * We keep props limited. No dangerouslySetInnerHTML.
+ * You can expand allowed props gradually.
+ */
+const UiPropsSchema = z
+  .object({
+    // common
+    title: z.string().max(500).optional(),
+    role: z.string().max(200).optional(),
+    "aria-label": z.string().max(200).optional(),
+    "aria-controls": z.string().max(200).optional(),
+    "aria-current": zSafePropValue.optional(),
+    "aria-describedby": z.string().max(200).optional(),
+    "aria-disabled": zSafePropValue.optional(),
+    "aria-expanded": zSafePropValue.optional(),
+    "aria-hidden": zSafePropValue.optional(),
+    "aria-invalid": zSafePropValue.optional(),
+    "aria-labelledby": z.string().max(200).optional(),
+    "aria-live": z.string().max(50).optional(),
+    "aria-pressed": zSafePropValue.optional(),
+    "aria-required": zSafePropValue.optional(),
+    "aria-selected": zSafePropValue.optional(),
+    "aria-checked": zSafePropValue.optional(),
+    "aria-valuemax": zSafePropValue.optional(),
+    "aria-valuemin": zSafePropValue.optional(),
+    "aria-valuenow": zSafePropValue.optional(),
+    "aria-valuetext": z.string().max(200).optional(),
+    "aria-busy": zSafePropValue.optional(),
+
+    // input-ish
+    placeholder: z.string().max(200).optional(),
+    type: z.string().max(50).optional(),
+    name: z.string().max(200).optional(),
+    value: z.union([z.string(), z.number(), z.boolean()]).optional(),
+    checked: z.union([z.boolean(), z.string()]).optional(),
+    disabled: z.union([z.boolean(), z.string()]).optional(),
+
+    // links + media
+    href: z.string().max(UI_LIMITS.MAX_URL_LEN).optional(),
+    target: z.enum(["_blank", "_self"]).optional(),
+    rel: z.string().max(200).optional(),
+    src: z.string().max(UI_LIMITS.MAX_URL_LEN).optional(),
+    alt: z.string().max(500).optional(),
+    loading: z.enum(["eager", "lazy"]).optional(),
+    decoding: z.enum(["auto", "async", "sync"]).optional(),
+
+    // sizing + constraints
+    width: z.union([z.string(), z.number()]).optional(),
+    height: z.union([z.string(), z.number()]).optional(),
+    rows: z.number().int().min(1).max(1000).optional(),
+    cols: z.number().int().min(1).max(2000).optional(),
+    min: z.union([z.string(), z.number()]).optional(),
+    max: z.union([z.string(), z.number()]).optional(),
+    step: z.union([z.string(), z.number()]).optional(),
+    minLength: z.number().int().min(0).max(10000).optional(),
+    maxLength: z.number().int().min(0).max(10000).optional(),
+
+    // label
+    htmlFor: z.string().max(200).optional(),
+
+    // svg-ish
+    viewBox: z.string().max(200).optional(),
+    preserveAspectRatio: z.string().max(200).optional(),
+    fill: z.string().max(200).optional(),
+    fillRule: z.string().max(50).optional(),
+    clipRule: z.string().max(50).optional(),
+    stroke: z.string().max(200).optional(),
+    strokeWidth: z.union([z.string(), z.number()]).optional(),
+    strokeLinecap: z.string().max(50).optional(),
+    strokeLinejoin: z.string().max(50).optional(),
+    d: z.string().max(2000).optional(),
+    cx: z.union([z.string(), z.number()]).optional(),
+    cy: z.union([z.string(), z.number()]).optional(),
+    r: z.union([z.string(), z.number()]).optional(),
+    x: z.union([z.string(), z.number()]).optional(),
+    y: z.union([z.string(), z.number()]).optional(),
+    opacity: z.union([z.string(), z.number()]).optional(),
+  })
+  .catchall(zSafePropValue)
+  .superRefine((props, ctx) => {
+    if (!props) return;
+    for (const key of Object.keys(props)) {
+      if (UI_BASE_PROP_KEYS.has(key)) continue;
+      if (key.startsWith("aria-") || key.startsWith("data-")) {
+        if (key.length > UI_LIMITS.MAX_KEY_LEN) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `Prop key too long: ${key}`,
+            path: [key],
+          });
+        }
+        continue;
+      }
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Unsupported prop: ${key}`,
+        path: [key],
+      });
+    }
+  })
+  .optional();
+
+export const UiBindSchema = z
+  .object({
+    // bind node value/checked to local state key
+    valueKey: zSafeKey.optional(),
+    checkedKey: zSafeKey.optional(),
+  })
+  .strict()
+  .optional();
+
+export type UiBind = z.infer<typeof UiBindSchema>;
+
+export const UiNodeSchema: z.ZodType<any> = z.lazy(() =>
+  z
+    .object({
+      id: zSafeId.optional(),
+      type: z.string().min(1).max(50), // allowlist enforced on client
+      className: zSafeClassName.optional(),
+      props: UiPropsSchema,
+      events: UiEventMapSchema.optional(),
+      bind: UiBindSchema,
+      widgetId: zSafeId.optional(),
+      widgetProps: z.record(zSafeKey, z.unknown()).optional(),
+      slots: z
+        .record(
+          zSafeKey,
+          z.array(z.union([zSafeText, UiNodeSchema])).max(UI_LIMITS.MAX_NODES)
+        )
+        .optional(),
+      slotName: zSafeKey.optional(),
+      children: z
+        .array(z.union([zSafeText, UiNodeSchema]))
+        .max(UI_LIMITS.MAX_NODES) // soft guard; hard guard below
+        .optional(),
+    })
+    .strict()
+    .superRefine((node, ctx) => {
+      const isWidget = node.type === "widget";
+      const isSlot = node.type === "slot";
+
+      if (isWidget) {
+        if (!node.widgetId) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "widgetId is required for widget nodes",
+          });
+        }
+        if (node.className || node.props || node.events || node.bind) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message:
+              "widget nodes cannot use className/props/events/bind; use widgetProps and slots",
+          });
+        }
+        if (node.children) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "widget nodes must use slots instead of children",
+          });
+        }
+        if (node.slotName) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "widget nodes cannot define slotName",
+          });
+        }
+      } else if (isSlot) {
+        if (!node.slotName) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "slotName is required for slot nodes",
+          });
+        }
+        if (
+          node.className ||
+          node.props ||
+          node.events ||
+          node.bind ||
+          node.children ||
+          node.widgetId ||
+          node.widgetProps ||
+          node.slots
+        ) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "slot nodes cannot include other node fields",
+          });
+        }
+      } else {
+        if (node.widgetId || node.widgetProps || node.slots || node.slotName) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "reserved widget/slot fields are not allowed on UI nodes",
+          });
+        }
+      }
+    })
+);
+
+export type UiNode = z.infer<typeof UiNodeSchema>;
+
+// ------------------ Messages ------------------
+
+export const UiTemplateSchema = z
+  .object({
+    schema: z.literal("ui.v1"),
+    root: UiNodeSchema,
+  })
+  .strict();
+
+export type UiTemplate = z.infer<typeof UiTemplateSchema>;
+
+const WidgetPropSchema = z
+  .object({
+    type: z.enum(["string", "number", "boolean", "json"]),
+    required: z.boolean().optional(),
+    default: z.unknown().optional(),
+  })
+  .strict();
+
+export const WidgetPolicySchema = z
+  .object({
+    allowedTags: z.array(z.string().min(1).max(50)).optional(),
+    allowedProps: z.array(zSafeKey).optional(),
+    allowedActions: z.array(UiActionTypeSchema).optional(),
+    maxNodes: z.number().int().min(1).max(UI_LIMITS.MAX_NODES).optional(),
+    maxDepth: z.number().int().min(1).max(UI_LIMITS.MAX_DEPTH).optional(),
+  })
+  .strict()
+  .optional();
+
+export const WidgetDefinitionSchema = z
+  .object({
+    schema: z.literal("widget.v1"),
+    widgetId: zSafeId,
+    version: z.string().min(1).max(50),
+    template: UiTemplateSchema,
+    props: z.record(zSafeKey, WidgetPropSchema).optional(),
+    slots: z
+      .record(zSafeKey, z.object({ required: z.boolean().optional() }).strict())
+      .optional(),
+    policy: WidgetPolicySchema,
+  })
+  .strict();
+
+export type WidgetDefinition = z.infer<typeof WidgetDefinitionSchema>;
+
+export const FlowOutputSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("text"), text: zSafeText }),
+  z.object({ kind: z.literal("markdown"), markdown: zSafeText }),
+  z.object({
+    kind: z.literal("ui"),
+    templateId: z.string().min(1).max(200),
+    data: z.record(z.string(), z.unknown()).optional(),
+  }),
+]);
+
+export type FlowOutput = z.infer<typeof FlowOutputSchema>;
+
+export const WsClientEventSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("ui_event"),
+    name: z.string().min(1).max(200),
+    payload: z.record(z.string(), z.unknown()).optional(),
+  }),
+]);
+
+export type WsClientEvent = z.infer<typeof WsClientEventSchema>;
+
+export const WsServerMessageSchema = z.object({
+  kind: z.literal("flow_output"),
+  output: FlowOutputSchema,
+});
+
+export type WsServerMessage = z.infer<typeof WsServerMessageSchema>;
+
+// ------------------ Hard guard helpers ------------------
+
+export function countNodes(root: UiNode): { nodes: number; depth: number } {
+  let nodes = 0;
+  let maxDepth = 0;
+
+  function walk(node: UiNode, depth: number) {
+    nodes += 1;
+    if (depth > maxDepth) maxDepth = depth;
+
+    const children = node.children ?? [];
+    for (const c of children) {
+      if (typeof c === "string") continue;
+      walk(c, depth + 1);
+    }
+
+    const slots = node.slots ? Object.values(node.slots) : [];
+    for (const slotNodes of slots as any) {
+      for (const c of slotNodes) {
+        if (typeof c === "string") continue;
+        walk(c, depth + 1);
+      }
+    }
+  }
+
+  walk(root, 1);
+  return { nodes, depth: maxDepth };
+}
+
+export function assertWithinLimits(template: UiTemplate): void {
+  const { nodes, depth } = countNodes(template.root);
+  if (nodes > UI_LIMITS.MAX_NODES) {
+    throw new Error(
+      `UI template too large: nodes=${nodes} > ${UI_LIMITS.MAX_NODES}`
+    );
+  }
+  if (depth > UI_LIMITS.MAX_DEPTH) {
+    throw new Error(
+      `UI template too deep: depth=${depth} > ${UI_LIMITS.MAX_DEPTH}`
+    );
+  }
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}