@femtomc/mu-core 26.2.106 → 26.2.108

package/dist/ui.js

@@ -0,0 +1,332 @@
+import { z } from "zod";
+export const UiToneSchema = z.enum(["info", "success", "warning", "error", "muted", "accent", "dim"]);
+export const UI_CONTRACT_VERSION = 1;
+const UI_DOC_TITLE_MAX_LENGTH = 256;
+const UI_DOC_SUBTITLE_MAX_LENGTH = 512;
+const UI_DOC_SUMMARY_MAX_LENGTH = 1024;
+const UI_COMPONENT_LIMIT = 64;
+const UI_TEXT_COMPONENT_MAX_LENGTH = 2048;
+const UI_LIST_ITEM_LIMIT = 32;
+const UI_LIST_ITEM_DETAIL_MAX_LENGTH = 1024;
+const UI_KEY_VALUE_ROW_LIMIT = 32;
+const UI_KEY_MAX_LENGTH = 64;
+const UI_VALUE_MAX_LENGTH = 256;
+const UI_ACTION_LIMIT = 32;
+const UI_ACTION_LABEL_MAX_LENGTH = 128;
+const UI_ACTION_DESCRIPTION_MAX_LENGTH = 512;
+const UI_CALLBACK_TOKEN_MAX_LENGTH = 128;
+const UI_REVISION_ID_MAX_LENGTH = 64;
+const NonEmptyText = (max) => z.string().trim().min(1).max(max);
+const NonEmptyId = z.string().trim().min(1).max(64);
+const CallbackTokenSchema = z.string().trim().min(1).max(UI_CALLBACK_TOKEN_MAX_LENGTH);
+export const UiListItemSchema = z
+    .object({
+    id: NonEmptyId,
+    label: NonEmptyText(UI_ACTION_LABEL_MAX_LENGTH),
+    detail: NonEmptyText(UI_LIST_ITEM_DETAIL_MAX_LENGTH).optional(),
+    tone: UiToneSchema.optional(),
+})
+    .strict();
+export const UiKeyValueRowSchema = z
+    .object({
+    key: NonEmptyText(UI_KEY_MAX_LENGTH),
+    value: NonEmptyText(UI_VALUE_MAX_LENGTH),
+    tone: UiToneSchema.optional(),
+})
+    .strict();
+export const UiComponentTextSchema = z
+    .object({
+    kind: z.literal("text"),
+    id: NonEmptyId,
+    text: NonEmptyText(UI_TEXT_COMPONENT_MAX_LENGTH),
+    tone: UiToneSchema.optional(),
+    metadata: z.record(z.string(), z.unknown()).default({}),
+})
+    .strict();
+export const UiComponentListSchema = z
+    .object({
+    kind: z.literal("list"),
+    id: NonEmptyId,
+    title: NonEmptyText(UI_DOC_SUBTITLE_MAX_LENGTH).optional(),
+    items: z.array(UiListItemSchema).min(1).max(UI_LIST_ITEM_LIMIT),
+    metadata: z.record(z.string(), z.unknown()).default({}),
+})
+    .strict();
+export const UiComponentKeyValueSchema = z
+    .object({
+    kind: z.literal("key_value"),
+    id: NonEmptyId,
+    title: NonEmptyText(UI_DOC_SUBTITLE_MAX_LENGTH).optional(),
+    rows: z.array(UiKeyValueRowSchema).min(1).max(UI_KEY_VALUE_ROW_LIMIT),
+    metadata: z.record(z.string(), z.unknown()).default({}),
+})
+    .strict();
+export const UiComponentDividerSchema = z
+    .object({
+    kind: z.literal("divider"),
+    id: NonEmptyId,
+    metadata: z.record(z.string(), z.unknown()).default({}),
+})
+    .strict();
+export const UiComponentSchema = z.discriminatedUnion("kind", [
+    UiComponentTextSchema,
+    UiComponentListSchema,
+    UiComponentKeyValueSchema,
+    UiComponentDividerSchema,
+]);
+export const UiActionKindSchema = z.enum(["primary", "secondary", "danger", "link"]);
+export const UiActionSchema = z
+    .object({
+    id: NonEmptyId,
+    label: NonEmptyText(UI_ACTION_LABEL_MAX_LENGTH),
+    kind: UiActionKindSchema.optional(),
+    description: NonEmptyText(UI_ACTION_DESCRIPTION_MAX_LENGTH).optional(),
+    component_id: NonEmptyId.optional(),
+    callback_token: CallbackTokenSchema.optional(),
+    payload: z.record(z.string(), z.unknown()).default({}),
+    metadata: z.record(z.string(), z.unknown()).default({}),
+})
+    .strict();
+export const UiRevisionSchema = z
+    .object({
+    id: NonEmptyText(UI_REVISION_ID_MAX_LENGTH),
+    version: z.number().int().nonnegative(),
+})
+    .strict();
+export const UiDocSchema = z
+    .object({
+    v: z.literal(UI_CONTRACT_VERSION).default(UI_CONTRACT_VERSION),
+    ui_id: NonEmptyId,
+    title: NonEmptyText(UI_DOC_TITLE_MAX_LENGTH),
+    summary: NonEmptyText(UI_DOC_SUMMARY_MAX_LENGTH).optional(),
+    components: z.array(UiComponentSchema).min(1).max(UI_COMPONENT_LIMIT),
+    actions: z.array(UiActionSchema).max(UI_ACTION_LIMIT).default([]),
+    revision: UiRevisionSchema,
+    updated_at_ms: z.number().int().nonnegative(),
+    metadata: z.record(z.string(), z.unknown()).default({}),
+})
+    .strict();
+export const UI_STATUS_PROFILE_NAMES = ["planning", "subagents", "control-flow", "model-routing"];
+export const UiEventSchema = z
+    .object({
+    ui_id: NonEmptyId,
+    action_id: NonEmptyId,
+    component_id: NonEmptyId.optional().nullable(),
+    revision: UiRevisionSchema,
+    callback_token: CallbackTokenSchema.optional(),
+    payload: z.record(z.string(), z.unknown()).default({}),
+    created_at_ms: z.number().int().nonnegative(),
+    metadata: z.record(z.string(), z.unknown()).default({}),
+})
+    .strict();
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseUiDocCandidate(value) {
+    const parsed = UiDocSchema.safeParse(value);
+    if (!parsed.success) {
+        return null;
+    }
+    return parsed.data;
+}
+const UI_PROFILE_VARIANTS = ["status", "interactive"];
+const UI_STATUS_PROFILE_UI_IDS = {
+    planning: "ui:planning",
+    subagents: "ui:subagents",
+    "control-flow": "ui:control-flow",
+    "model-routing": "ui:model-routing",
+};
+const UI_STATUS_PROFILE_COMPONENT_RECOMMENDATIONS = {
+    planning: ["key_value", "list"],
+    subagents: ["key_value", "list"],
+    "control-flow": ["key_value"],
+    "model-routing": ["key_value", "list"],
+};
+function isUiStatusProfileName(value) {
+    return UI_STATUS_PROFILE_NAMES.includes(value);
+}
+function isUiProfileVariant(value) {
+    return UI_PROFILE_VARIANTS.includes(value);
+}
+function uiProfileMetadata(doc) {
+    const raw = doc.metadata.profile;
+    if (!isPlainObject(raw)) {
+        return null;
+    }
+    return raw;
+}
+function uiStatusProfileNameFromDoc(doc) {
+    const profile = uiProfileMetadata(doc);
+    if (!profile) {
+        return null;
+    }
+    const raw = profile.id;
+    if (typeof raw !== "string") {
+        return null;
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (!normalized || !isUiStatusProfileName(normalized)) {
+        return null;
+    }
+    return normalized;
+}
+function hasUiComponentKind(doc, kind) {
+    return doc.components.some((component) => component.kind === kind);
+}
+function hasProfileSnapshotCompact(profile) {
+    const snapshot = profile.snapshot;
+    if (!isPlainObject(snapshot)) {
+        return false;
+    }
+    const compact = snapshot.compact;
+    return typeof compact === "string" && compact.trim().length > 0;
+}
+function uiDocCandidates(input) {
+    if (Array.isArray(input)) {
+        return input;
+    }
+    if (isPlainObject(input)) {
+        return [input];
+    }
+    return [];
+}
+function normalizedUiDocLimit(limit) {
+    if (typeof limit !== "number" || !Number.isFinite(limit)) {
+        return 12;
+    }
+    const parsed = Math.trunc(limit);
+    if (parsed < 1) {
+        return 1;
+    }
+    if (parsed > 64) {
+        return 64;
+    }
+    return parsed;
+}
+function canonicalizeJson(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => canonicalizeJson(entry));
+    }
+    if (!isPlainObject(value)) {
+        return value;
+    }
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+        const nextValue = value[key];
+        if (nextValue === undefined) {
+            continue;
+        }
+        out[key] = canonicalizeJson(nextValue);
+    }
+    return out;
+}
+export function stableSerializeJson(value, opts = {}) {
+    const normalized = canonicalizeJson(value);
+    const text = JSON.stringify(normalized, null, opts.pretty ? 2 : undefined);
+    return text ?? "null";
+}
+function deterministicUiDocChoice(left, right) {
+    if (left.revision.version !== right.revision.version) {
+        return left.revision.version > right.revision.version ? left : right;
+    }
+    if (left.updated_at_ms !== right.updated_at_ms) {
+        return left.updated_at_ms > right.updated_at_ms ? left : right;
+    }
+    const leftText = stableSerializeJson(left);
+    const rightText = stableSerializeJson(right);
+    return leftText <= rightText ? left : right;
+}
+export function parseUiDoc(input) {
+    return parseUiDocCandidate(input);
+}
+export function resolveUiStatusProfileName(input) {
+    const doc = parseUiDocCandidate(input);
+    if (!doc) {
+        return null;
+    }
+    return uiStatusProfileNameFromDoc(doc);
+}
+export function uiStatusProfileWarnings(input) {
+    const doc = parseUiDocCandidate(input);
+    if (!doc) {
+        return [];
+    }
+    const profileName = uiStatusProfileNameFromDoc(doc);
+    if (!profileName) {
+        return [];
+    }
+    const warnings = [];
+    const profile = uiProfileMetadata(doc);
+    if (!profile) {
+        return warnings;
+    }
+    const rawVariant = typeof profile.variant === "string" ? profile.variant.trim().toLowerCase() : "";
+    let variant = "status";
+    if (rawVariant.length > 0) {
+        if (isUiProfileVariant(rawVariant)) {
+            variant = rawVariant;
+        }
+        else {
+            warnings.push(`profile.id=${profileName} has unsupported metadata.profile.variant=${rawVariant}`);
+        }
+    }
+    if (variant !== "status") {
+        warnings.push(`profile.id=${profileName} status validation expects metadata.profile.variant=status (got ${variant})`);
+    }
+    const expectedUiId = UI_STATUS_PROFILE_UI_IDS[profileName];
+    if (doc.ui_id !== expectedUiId) {
+        warnings.push(`profile.id=${profileName} expects ui_id=${expectedUiId} (got ${doc.ui_id})`);
+    }
+    if (!doc.summary) {
+        warnings.push(`profile.id=${profileName} recommends summary for deterministic status fallback`);
+    }
+    if (!hasProfileSnapshotCompact(profile)) {
+        warnings.push(`profile.id=${profileName} recommends metadata.profile.snapshot.compact`);
+    }
+    if (doc.actions.length > 0) {
+        warnings.push(`profile.id=${profileName} status docs should omit actions (got ${doc.actions.length})`);
+    }
+    for (const kind of UI_STATUS_PROFILE_COMPONENT_RECOMMENDATIONS[profileName]) {
+        if (!hasUiComponentKind(doc, kind)) {
+            warnings.push(`profile.id=${profileName} recommends a ${kind} component`);
+        }
+    }
+    return warnings;
+}
+export function normalizeUiDocs(input, opts = {}) {
+    const maxDocs = normalizedUiDocLimit(opts.maxDocs);
+    const byId = new Map();
+    for (const candidate of uiDocCandidates(input)) {
+        const parsed = parseUiDocCandidate(candidate);
+        if (!parsed) {
+            continue;
+        }
+        const current = byId.get(parsed.ui_id);
+        if (!current) {
+            byId.set(parsed.ui_id, parsed);
+            continue;
+        }
+        byId.set(parsed.ui_id, deterministicUiDocChoice(current, parsed));
+    }
+    const docs = [...byId.values()].sort((a, b) => a.ui_id.localeCompare(b.ui_id));
+    if (docs.length <= maxDocs) {
+        return docs;
+    }
+    return docs.slice(0, maxDocs);
+}
+export function uiDocRevisionConflict(left, right) {
+    if (left.ui_id !== right.ui_id) {
+        return false;
+    }
+    if (left.revision.version !== right.revision.version) {
+        return false;
+    }
+    return stableSerializeJson(left) !== stableSerializeJson(right);
+}
+export function parseUiEvent(input) {
+    const parsed = UiEventSchema.safeParse(input);
+    if (!parsed.success) {
+        return null;
+    }
+    return parsed.data;
+}

package/package.json

@@ -1,34 +1,34 @@
 {
-  "name": "@femtomc/mu-core",
-  "version": "26.2.106",
-  "description": "Core primitives for mu: IDs, events, schemas, and persistence interfaces.",
-  "keywords": [
-    "mu",
-    "agent",
-    "core",
-    "events"
-  ],
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./browser": {
-      "types": "./dist/browser/index.d.ts",
-      "default": "./dist/browser/index.js"
-    },
-    "./node": {
-      "types": "./dist/node/index.d.ts",
-      "default": "./dist/node/index.js"
-    }
-  },
-  "files": [
-    "dist/**"
-  ],
-  "dependencies": {
-    "zod": "^4.1.9"
-  }
+	"name": "@femtomc/mu-core",
+	"version": "26.2.108",
+	"description": "Core primitives for mu: IDs, events, schemas, and persistence interfaces.",
+	"keywords": [
+		"mu",
+		"agent",
+		"core",
+		"events"
+	],
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./browser": {
+			"types": "./dist/browser/index.d.ts",
+			"default": "./dist/browser/index.js"
+		},
+		"./node": {
+			"types": "./dist/node/index.d.ts",
+			"default": "./dist/node/index.js"
+		}
+	},
+	"files": [
+		"dist/**"
+	],
+	"dependencies": {
+		"zod": "^4.1.9"
+	}
 }