@morit/cli 1.0.0 → 1.1.1

package/src/workspace.js

@@ -41,6 +41,18 @@ const UI_IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const UI_STATE_KEY = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
 const UI_BINDING = /^(?:state|data|item)(?:\.[A-Za-z0-9_-]+){0,12}$/;
 const UI_TEMPLATE_BINDING = /\{\{\s*([^{}]+?)\s*\}\}/g;
+const UI_SINGLE_TEMPLATE_BINDING = /^\{\{\s*([^{}]+?)\s*\}\}$/;
+const UI_ASSET_PATH = /^assets\/[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*\.(?:gif|jpe?g|png|webp)$/i;
+const UI_HEX_COLOR = /^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$/;
+const UI_COLOR_TOKENS = new Set([
+  "primary", "on_primary", "primary_container", "on_primary_container",
+  "secondary", "on_secondary", "secondary_container", "on_secondary_container",
+  "tertiary", "on_tertiary", "tertiary_container", "on_tertiary_container",
+  "error", "on_error", "error_container", "on_error_container", "surface",
+  "on_surface", "surface_variant", "on_surface_variant", "outline", "outline_variant",
+  "inverse_surface", "inverse_on_surface", "inverse_primary", "shadow", "scrim", "transparent",
+]);
+const UI_ICON_TOKENS = new Set(contract.ui_runtime.icon_tokens);
 const MANIFEST_FIELDS = new Set(contract.manifest_fields);
 const CAPABILITY_KINDS = new Set(contract.capability_kinds);
 const CAPABILITY_FIELDS = new Set(contract.object_fields.capability);
@@ -135,7 +147,7 @@ export class LocalWorkspace {
       version: "1.0.0",
       cloud_project_id: null,
       required_secrets: [],
-      min_morit_version: "1.7.5",
+      min_morit_version: "1.7.6",
       max_morit_version: "1.999.999",
       permissions: [],
       capabilities: [],
@@ -739,11 +751,11 @@ function validateManifest(manifest, files) {
   if (manifest.category !== undefined && !/^[a-z][a-z0-9_-]{1,39}$/.test(String(manifest.category))) {
     throw new Error("manifest.category is invalid");
   }
-  const keywords = manifest.keywords || [];
+  const keywords = manifest.keywords === undefined ? [] : manifest.keywords;
   if (!Array.isArray(keywords) || keywords.length > 12 || new Set(keywords).size !== keywords.length || keywords.some(
     (value) => typeof value !== "string" || !value.trim() || value.length > 40
   )) throw new Error("manifest.keywords must contain up to 12 unique short strings");
-  const developer = manifest.developer || {};
+  const developer = manifest.developer === undefined ? {} : manifest.developer;
   assertObject(developer, "manifest.developer");
   rejectUnknownFields(developer, DEVELOPER_FIELDS, "manifest.developer");
   if (developer.name !== undefined && (typeof developer.name !== "string" || developer.name.length > 120)) {
@@ -762,15 +774,15 @@ function validateManifest(manifest, files) {
   for (const field of ["version", "min_morit_version", "max_morit_version"]) {
     if (!VERSION.test(String(manifest[field] || ""))) throw new Error(`manifest.${field} must be a semantic version`);
   }
-  const requestedPermissions = validatePermissions(manifest.permissions || [], "manifest.permissions");
+  const requestedPermissions = validatePermissions(manifest.permissions, "manifest.permissions");
   if (!["purge", "retain"].includes(manifest.data_policy)) throw new Error("manifest.data_policy must be purge or retain");
   const capabilities = objectCollection(manifest.capabilities, "manifest.capabilities", 64);
   const uiExtensions = objectCollection(manifest.ui_extensions, "manifest.ui_extensions", 64);
-  const credentials = objectCollection(manifest.credentials || [], "manifest.credentials", 16);
-  const slashCommands = objectCollection(manifest.slash_commands || [], "manifest.slash_commands", 32);
-  const connectors = objectCollection(manifest.connectors || [], "manifest.connectors", 32);
-  const dependencies = objectCollection(manifest.dependencies || [], "manifest.dependencies", 16);
-  const requiredSecrets = objectCollection(manifest.required_secrets || [], "manifest.required_secrets", 32);
+  const credentials = objectCollection(manifest.credentials === undefined ? [] : manifest.credentials, "manifest.credentials", 16);
+  const slashCommands = objectCollection(manifest.slash_commands === undefined ? [] : manifest.slash_commands, "manifest.slash_commands", 32);
+  const connectors = objectCollection(manifest.connectors === undefined ? [] : manifest.connectors, "manifest.connectors", 32);
+  const dependencies = objectCollection(manifest.dependencies === undefined ? [] : manifest.dependencies, "manifest.dependencies", 16);
+  const requiredSecrets = objectCollection(manifest.required_secrets === undefined ? [] : manifest.required_secrets, "manifest.required_secrets", 32);
   if (!capabilities.length && !uiExtensions.length) throw new Error("plugin does not declare any extension");
 
   const capabilityIds = new Set();
@@ -782,13 +794,13 @@ function validateManifest(manifest, files) {
     if (!CAPABILITY_KINDS.has(capability.kind)) throw new Error(`unknown capability kind: ${capability.kind}`);
     requireText(capability.title, 80, `capability ${capability.id} title`);
     requireText(capability.description, 500, `capability ${capability.id} description`);
-    const permissions = validatePermissions(capability.permissions || [], `capability ${capability.id} permissions`);
+    const permissions = validatePermissions(capability.permissions, `capability ${capability.id} permissions`);
     requireSubset(permissions, requestedPermissions, `capability ${capability.id} permissions`);
-    const timeout = capability.timeout_seconds ?? 10;
+    const timeout = capability.timeout_seconds === undefined ? 10 : capability.timeout_seconds;
     if (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout < 0.1 || timeout > 30) {
       throw new Error(`capability ${capability.id} timeout must be between 0.1 and 30 seconds`);
     }
-    const runtime = capability.runtime || {};
+    const runtime = capability.runtime === undefined ? {} : capability.runtime;
     assertObject(runtime, `capability ${capability.id} runtime`);
     assertJsonSize(runtime, 32 * 1024, `capability ${capability.id} runtime`);
     const adapter = runtime.adapter;
@@ -810,14 +822,17 @@ function validateManifest(manifest, files) {
     requireUniqueIdentifier(extension.id, uiIds, "UI extension");
     if (!UI_POINTS.has(extension.point)) throw new Error(`unknown UI extension point: ${extension.point}`);
     requireText(extension.title, 80, `UI ${extension.id} title`);
-    const order = extension.order ?? 0;
+    const order = extension.order === undefined ? 0 : extension.order;
     if (!Number.isInteger(order) || order < -10000 || order > 10000) throw new Error(`UI ${extension.id} order is invalid`);
-    const permissions = validatePermissions(extension.permissions || [], `UI ${extension.id} permissions`);
+    const permissions = validatePermissions(extension.permissions, `UI ${extension.id} permissions`);
     requireSubset(permissions, requestedPermissions, `UI ${extension.id} permissions`);
-    assertObject(extension.config || {}, `UI ${extension.id} config`);
-    assertJsonSize(extension.config || {}, 32 * 1024, `UI ${extension.id} config`);
+    const extensionConfig = extension.config === undefined ? {} : extension.config;
+    assertObject(extensionConfig, `UI ${extension.id} config`);
+    // Twelve legal component levels add an object and a children array per
+    // level before semantic UI validation runs.
+    assertJsonSize(extensionConfig, 32 * 1024, `UI ${extension.id} config`, 40);
   }
-  for (const extension of uiExtensions) validateUiConfig(extension, capabilities, uiIds);
+  for (const extension of uiExtensions) validateUiConfig(extension, capabilities, uiIds, files);
 
   const credentialIds = validateCredentials(credentials, requestedPermissions);
   const secretIds = validateRequiredSecrets(requiredSecrets);
@@ -896,15 +911,15 @@ function requireText(value, maximum, label) {
   }
 }
 
-function assertJsonSize(value, maximum, label) {
-  validateJsonValue(value, 0, label);
+function assertJsonSize(value, maximum, label, maximumDepth = 12) {
+  validateJsonValue(value, 0, label, maximumDepth);
   if (Buffer.byteLength(JSON.stringify(value), "utf8") > maximum) {
     throw new Error(`${label} is too large`);
   }
 }
 
-function validateJsonValue(value, depth, label) {
-  if (depth > 12) throw new Error(`${label} is too deeply nested`);
+function validateJsonValue(value, depth, label, maximumDepth) {
+  if (depth > maximumDepth) throw new Error(`${label} is too deeply nested`);
   if (value === null || typeof value === "boolean" || typeof value === "string") return;
   if (typeof value === "number") {
     if (!Number.isFinite(value)) throw new Error(`${label} contains a non-finite number`);
@@ -912,14 +927,14 @@ function validateJsonValue(value, depth, label) {
   }
   if (Array.isArray(value)) {
     if (value.length > 256) throw new Error(`${label} contains an oversized array`);
-    for (const item of value) validateJsonValue(item, depth + 1, label);
+    for (const item of value) validateJsonValue(item, depth + 1, label, maximumDepth);
     return;
   }
   if (value && typeof value === "object") {
     if (Object.keys(value).length > 256) throw new Error(`${label} contains an oversized object`);
     for (const [key, item] of Object.entries(value)) {
       if (key.length > 256) throw new Error(`${label} contains an oversized key`);
-      validateJsonValue(item, depth + 1, label);
+      validateJsonValue(item, depth + 1, label, maximumDepth);
     }
     return;
   }
@@ -938,7 +953,7 @@ function validateCredentials(credentials, requestedPermissions) {
     requireUniqueIdentifier(credential.id, ids, "credential");
     requireText(credential.label, 80, `credential ${credential.id} label`);
     requireText(credential.description, 500, `credential ${credential.id} description`);
-    const kind = credential.kind || "api_token";
+    const kind = credential.kind === undefined ? "api_token" : credential.kind;
     if (!CREDENTIAL_KINDS.has(kind)) throw new Error(`credential ${credential.id} kind is invalid`);
     for (const field of ["required", "allow_multiple"]) {
       if (credential[field] !== undefined && typeof credential[field] !== "boolean") {
@@ -1009,20 +1024,20 @@ function validateConnectors(connectors, credentialIds, secretIds) {
     if (endpoint !== undefined && endpoint !== null && (
       typeof endpoint !== "string" || !endpoint.startsWith("https://") || endpoint.length > 2048 || /[\r\n@]/.test(endpoint)
     )) throw new Error(`connector ${connector.id} endpoint is invalid`);
-    const timeout = connector.timeout_seconds ?? 10;
+    const timeout = connector.timeout_seconds === undefined ? 10 : connector.timeout_seconds;
     if (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout < 0.1 || timeout > 30) {
       throw new Error(`connector ${connector.id} timeout is invalid`);
     }
-    const retry = connector.retry || {};
+    const retry = connector.retry === undefined ? {} : connector.retry;
     assertObject(retry, `connector ${connector.id} retry`);
     rejectUnknownFields(retry, new Set(["max_attempts"]), `connector ${connector.id} retry`);
-    const attempts = retry.max_attempts ?? 2;
+    const attempts = retry.max_attempts === undefined ? 2 : retry.max_attempts;
     if (!Number.isInteger(attempts) || attempts < 1 || attempts > 4) throw new Error(`connector ${connector.id} retry count is invalid`);
-    const rate = connector.rate_limit || {};
+    const rate = connector.rate_limit === undefined ? {} : connector.rate_limit;
     assertObject(rate, `connector ${connector.id} rate_limit`);
     rejectUnknownFields(rate, new Set(["requests", "period_seconds"]), `connector ${connector.id} rate_limit`);
-    const requests = rate.requests ?? 60;
-    const period = rate.period_seconds ?? 60;
+    const requests = rate.requests === undefined ? 60 : rate.requests;
+    const period = rate.period_seconds === undefined ? 60 : rate.period_seconds;
     if (!Number.isInteger(requests) || requests < 1 || requests > 10000 || !Number.isInteger(period) || period < 1 || period > 3600) {
       throw new Error(`connector ${connector.id} rate limit is invalid`);
     }
@@ -1053,15 +1068,16 @@ function validateDependencies(dependencies, pluginId) {
     }
     if (dependency.required !== undefined && typeof dependency.required !== "boolean") throw new Error(`dependency ${dependency.id} required must be boolean`);
     for (const [field, fallback] of [["min_version", "0.0.0"], ["max_version", "999.999.999"]]) {
-      if (!VERSION.test(String(dependency[field] || fallback))) throw new Error(`dependency ${dependency.id} ${field} is invalid`);
+      const version = dependency[field] === undefined ? fallback : dependency[field];
+      if (typeof version !== "string" || !VERSION.test(version)) throw new Error(`dependency ${dependency.id} ${field} is invalid`);
     }
     if (dependency.package_path !== undefined && dependency.package_path !== null) {
       const path = String(dependency.package_path).replaceAll("\\", "/");
       if (!/^children\/[A-Za-z0-9._-]+\.mplg$/.test(path) || path.length > 240) throw new Error(`dependency ${dependency.id} package_path is invalid`);
       dependency.package_path = path;
     }
-    const exposed = dependency.exposed_capabilities || [];
-    if (!Array.isArray(exposed) || exposed.length > 32 || new Set(exposed).size !== exposed.length || exposed.some((value) => !IDENTIFIER.test(String(value)))) {
+    const exposed = dependency.exposed_capabilities === undefined ? [] : dependency.exposed_capabilities;
+    if (!Array.isArray(exposed) || exposed.length > 32 || new Set(exposed).size !== exposed.length || exposed.some((value) => typeof value !== "string" || !IDENTIFIER.test(value))) {
       throw new Error(`dependency ${dependency.id} exposed_capabilities are invalid`);
     }
   }
@@ -1081,8 +1097,9 @@ function validateSlashCommands(commands, capabilities) {
     requireText(command.title, 80, `slash command ${command.id} title`);
     requireText(command.description, 500, `slash command ${command.id} description`);
     if (!executable.has(command.capability)) throw new Error(`slash command ${command.id} targets a non-executable capability`);
-    assertObject(command.argument_template || {}, `slash command ${command.id} argument_template`);
-    assertJsonSize(command.argument_template || {}, 16 * 1024, `slash command ${command.id} argument_template`);
+    const argumentTemplate = command.argument_template === undefined ? {} : command.argument_template;
+    assertObject(argumentTemplate, `slash command ${command.id} argument_template`);
+    assertJsonSize(argumentTemplate, 16 * 1024, `slash command ${command.id} argument_template`);
   }
 }
 
@@ -1107,7 +1124,8 @@ function validateRuntime(capability, runtime, permissions, credentials, connecto
   }
   if (adapter === "child_plugin") {
     const dependency = dependencyById.get(runtime.dependency_id);
-    if (!dependency || !(dependency.exposed_capabilities || []).includes(runtime.capability)) throw new Error("child_plugin requires an exposed dependency capability");
+    const exposed = dependency?.exposed_capabilities === undefined ? [] : dependency.exposed_capabilities;
+    if (!dependency || !Array.isArray(exposed) || !exposed.includes(runtime.capability)) throw new Error("child_plugin requires an exposed dependency capability");
   }
   if (adapter === "calendar_store") {
     if (!permissions.has("storage")) throw new Error("calendar_store requires storage permission");
@@ -1130,7 +1148,7 @@ function validateRuntimeReferences(capabilities, connectors, connectorIds, depen
   const connectorById = new Map(connectors.map((value) => [value.id, value]));
   const dependencyIds = new Set(dependencies.map((value) => value.id));
   for (const capability of capabilities) {
-    const runtime = capability.runtime || {};
+    const runtime = capability.runtime === undefined ? {} : capability.runtime;
     if (runtime.connector_id) {
       if (!connectorIds.has(runtime.connector_id)) throw new Error(`capability ${capability.id} references an unknown connector`);
       if (!["http_json", "mcp_http"].includes(runtime.adapter)) throw new Error(`capability ${capability.id} connector is unsupported by its runtime`);
@@ -1142,34 +1160,38 @@ function validateRuntimeReferences(capabilities, connectors, connectorIds, depen
   }
 }
 
-function validateUiConfig(extension, capabilities, routeIds) {
-  const config = extension.config || {};
+function validateUiConfig(extension, capabilities, routeIds, files) {
+  const config = extension.config === undefined ? {} : extension.config;
   const executable = new Set(capabilities.filter((value) => ["tool", "skill", "provider", "notification"].includes(value.kind)).map((value) => value.id));
   if (config.ui_schema === 2) {
-    if (config.placement !== undefined && !["card", "action"].includes(extension.point)) throw new Error("UI placement is only valid for home extensions");
+    if (config.placement != null && !["card", "action"].includes(extension.point)) throw new Error("UI placement is only valid for home extensions");
     validateUiRuntimeV2(config, executable, routeIds);
+    for (const asset of uiRuntimeAssetPaths(config.view)) {
+      if (!(asset in files)) throw new Error(`UI image asset is not packaged: ${asset}`);
+    }
     return;
   }
   const allowed = new Set(["icon", "description", "component", "sections", "actions", "capability", "label", "form"]);
   rejectUnknownFields(config, allowed, `UI ${extension.id} config`);
-  if (config.icon !== undefined && !IDENTIFIER.test(String(config.icon))) throw new Error(`UI ${extension.id} icon is invalid`);
+  if (config.icon !== undefined && (typeof config.icon !== "string" || !IDENTIFIER.test(config.icon))) throw new Error(`UI ${extension.id} icon is invalid`);
   if (config.description !== undefined) requireText(config.description, 240, `UI ${extension.id} description`);
   if (config.component !== undefined && !["action", "card", "settings_action"].includes(config.component)) throw new Error(`UI ${extension.id} component is invalid`);
-  const sections = config.sections || [];
+  const sections = config.sections === undefined ? [] : config.sections;
   if (!Array.isArray(sections) || sections.length > 12) throw new Error(`UI ${extension.id} sections are invalid`);
   for (const section of sections) {
     rejectUnknownFields(section, new Set(["heading", "body"]), `UI ${extension.id} section`);
     if (section.heading !== undefined) requireText(section.heading, 80, `UI ${extension.id} section heading`);
     requireText(section.body, 1200, `UI ${extension.id} section body`);
   }
-  const actions = config.actions || [];
+  const actions = config.actions === undefined ? [] : config.actions;
   if (!Array.isArray(actions) || actions.length > 6) throw new Error(`UI ${extension.id} actions are invalid`);
   const actionIds = new Set();
   for (const action of actions) {
     rejectUnknownFields(action, new Set(["id", "label", "capability", "style"]), `UI ${extension.id} action`);
     requireUniqueIdentifier(action.id, actionIds, `UI ${extension.id} action`);
     requireText(action.label, 60, `UI ${extension.id} action label`);
-    if (!executable.has(action.capability) || !["primary", "secondary"].includes(action.style || "secondary")) throw new Error(`UI ${extension.id} action is invalid`);
+    const style = action.style === undefined ? "secondary" : action.style;
+    if (!executable.has(action.capability) || !["primary", "secondary"].includes(style)) throw new Error(`UI ${extension.id} action is invalid`);
   }
   if ((config.capability === undefined) !== (config.label === undefined)) throw new Error(`UI ${extension.id} shorthand action is incomplete`);
   if (config.capability !== undefined && (actions.length || !executable.has(config.capability))) throw new Error(`UI ${extension.id} shorthand action is invalid`);
@@ -1207,22 +1229,24 @@ function validateLegacyUiForm(form, executable, extensionId) {
 }
 
 function validateUiRuntimeV2(config, executable, routes) {
-  rejectUnknownFields(config, new Set(["ui_schema", "icon", "description", "placement", "initial_state", "data_sources", "view"]), "UI Runtime v2");
+  rejectUnknownFields(config, new Set(contract.ui_runtime.config_fields), "UI Runtime v2");
   if (config.ui_schema !== 2) throw new Error("UI Runtime version must be 2");
-  optionalUiText(config.icon, 128, { identifier: true });
+  validateUiIcon(config.icon);
   optionalUiText(config.description, 240);
-  if (config.placement !== undefined) {
+  if (config.placement != null) {
     const placement = config.placement;
     rejectUnknownFields(placement, new Set(["section_id", "section_title", "section_order", "layout", "show_header"]), "UI placement");
     optionalUiText(placement.section_id, 128, { required: true, identifier: true });
     optionalUiText(placement.section_title, 80, { required: true });
-    const order = placement.section_order ?? 0;
+    const order = placement.section_order === undefined ? 0 : placement.section_order;
     if (!Number.isInteger(order) || order < -10000 || order > 10000) throw new Error("UI placement order is invalid");
-    if (!["stack", "horizontal", "grid"].includes(placement.layout || "stack")) throw new Error("UI placement layout is invalid");
-    if (typeof (placement.show_header ?? true) !== "boolean") throw new Error("UI placement show_header must be boolean");
+    const layout = placement.layout === undefined ? "stack" : placement.layout;
+    if (!["stack", "horizontal", "grid"].includes(layout)) throw new Error("UI placement layout is invalid");
+    const showHeader = placement.show_header === undefined ? true : placement.show_header;
+    if (typeof showHeader !== "boolean") throw new Error("UI placement show_header must be boolean");
   }
 
-  const state = config.initial_state || {};
+  const state = config.initial_state === undefined ? {} : config.initial_state;
   assertObject(state, "UI initial_state");
   if (Object.keys(state).length > 32) throw new Error("UI initial_state is too large");
   for (const [key, value] of Object.entries(state)) {
@@ -1231,12 +1255,13 @@ function validateUiRuntimeV2(config, executable, routes) {
   }
   const stateKeys = new Set(Object.keys(state));
 
-  const sources = config.data_sources || [];
+  const sources = config.data_sources === undefined ? [] : config.data_sources;
   if (!Array.isArray(sources) || sources.length > 8) throw new Error("UI data_sources are invalid");
   const sourceIds = new Set();
   for (const source of sources) {
     rejectUnknownFields(source, new Set(["id", "capability", "trigger", "query", "arguments", "refresh_seconds"]), "UI data source");
-    if (!UI_IDENTIFIER.test(String(source.id || "")) || sourceIds.has(source.id) || !executable.has(source.capability) || !["load", "manual"].includes(source.trigger || "load")) {
+    const trigger = source.trigger === undefined ? "load" : source.trigger;
+    if (typeof source.id !== "string" || !UI_IDENTIFIER.test(source.id) || sourceIds.has(source.id) || !executable.has(source.capability) || !["load", "manual"].includes(trigger)) {
       throw new Error("UI data source reference is invalid");
     }
     sourceIds.add(source.id);
@@ -1244,68 +1269,205 @@ function validateUiRuntimeV2(config, executable, routes) {
   for (const source of sources) {
     optionalUiTemplate(source.query, 2000);
     validateTemplateReferences(source.query, stateKeys, sourceIds);
-    assertObject(source.arguments || {}, "UI data source arguments");
-    validateUiBindingValue(source.arguments || {}, 0, stateKeys, sourceIds);
-    if (source.refresh_seconds !== undefined && (!Number.isInteger(source.refresh_seconds) || source.refresh_seconds < 30 || source.refresh_seconds > 86400)) {
+    const sourceArguments = source.arguments === undefined ? {} : source.arguments;
+    assertObject(sourceArguments, "UI data source arguments");
+    validateUiBindingValue(sourceArguments, 0, stateKeys, sourceIds);
+    if (source.refresh_seconds != null && (!Number.isInteger(source.refresh_seconds) || source.refresh_seconds < 30 || source.refresh_seconds > 86400)) {
       throw new Error("UI refresh must be between 30 and 86400 seconds");
     }
   }
+  validateUiTheme(config.theme);
+  validateUiAppBar(config.app_bar, executable, routes, sourceIds, stateKeys);
+  validateUiNavigation(config.navigation, executable, routes, sourceIds, stateKeys);
   assertObject(config.view, "UI Runtime v2 view");
-  validateUiNode(config.view, 0, { value: 0 }, executable, routes, sourceIds, stateKeys);
+  validateUiNode(config.view, 0, { value: 0 }, executable, routes, sourceIds, stateKeys, null);
+}
+
+function validateUiTheme(theme) {
+  if (theme == null) return;
+  rejectUnknownFields(theme, new Set(contract.ui_runtime.theme_fields), "UI theme");
+  const colors = theme.color_scheme === undefined ? {} : theme.color_scheme;
+  assertObject(colors, "UI color scheme");
+  const roles = new Set([...UI_COLOR_TOKENS].filter((value) => value !== "transparent"));
+  rejectUnknownFields(colors, roles, "UI color scheme");
+  for (const value of Object.values(colors)) {
+    if (typeof value !== "string" || !UI_HEX_COLOR.test(value)) throw new Error("UI theme color is invalid");
+  }
+  if (theme.radius !== undefined) validateUiNumber(theme.radius, "UI theme radius", 0, 64);
+  if (theme.spacing !== undefined) validateUiNumber(theme.spacing, "UI theme spacing", 0, 32);
+  const density = theme.density === undefined ? "standard" : theme.density;
+  if (!["compact", "standard", "comfortable"].includes(density)) throw new Error("UI theme density is invalid");
+}
+
+function validateUiAppBar(appBar, executable, routes, sources, stateKeys) {
+  if (appBar == null) return;
+  rejectUnknownFields(appBar, new Set(contract.ui_runtime.app_bar_fields), "UI app bar");
+  optionalUiTemplate(appBar.title, 120, true);
+  validateTemplateReferences(appBar.title, stateKeys, sources);
+  optionalUiTemplate(appBar.subtitle, 160);
+  validateTemplateReferences(appBar.subtitle, stateKeys, sources);
+  for (const key of ["center_title", "pinned"]) if (appBar[key] !== undefined && typeof appBar[key] !== "boolean") throw new Error("UI app bar flag is invalid");
+  const ids = new Set();
+  if (appBar.leading != null) ids.add(validateUiMenuItem(appBar.leading, executable, routes, sources, stateKeys, false));
+  const actions = appBar.actions === undefined ? [] : appBar.actions;
+  if (!Array.isArray(actions) || actions.length > 6) throw new Error("UI app bar actions are invalid");
+  for (const action of actions) {
+    const id = validateUiMenuItem(action, executable, routes, sources, stateKeys, false);
+    if (ids.has(id)) throw new Error("UI app bar action is duplicated");
+    ids.add(id);
+  }
+}
+
+function validateUiNavigation(navigation, executable, routes, sources, stateKeys) {
+  if (navigation == null) return;
+  rejectUnknownFields(navigation, new Set(contract.ui_runtime.navigation_fields), "UI navigation");
+  const navigationType = navigation.type === undefined ? "adaptive" : navigation.type;
+  if (!["tabs", "bar", "rail", "drawer", "adaptive"].includes(navigationType)) throw new Error("UI navigation type is invalid");
+  if (!Array.isArray(navigation.items) || navigation.items.length < 2 || navigation.items.length > 8) throw new Error("UI navigation items are invalid");
+  const selectedKey = navigation.selected_state_key;
+  if (selectedKey != null && (typeof selectedKey !== "string" || !stateKeys.has(selectedKey))) throw new Error("UI navigation state is unknown");
+  const persist = navigation.persist === undefined ? false : navigation.persist;
+  if (typeof persist !== "boolean") throw new Error("UI navigation persistence is invalid");
+  const labelBehavior = navigation.label_behavior === undefined ? "auto" : navigation.label_behavior;
+  if (!["auto", "always", "selected", "never"].includes(labelBehavior)) throw new Error("UI navigation label behavior is invalid");
+  if (navigation.rail_breakpoint !== undefined && (!Number.isInteger(navigation.rail_breakpoint) || navigation.rail_breakpoint < 480 || navigation.rail_breakpoint > 1600)) throw new Error("UI navigation breakpoint is invalid");
+  const ids = new Set();
+  for (const item of navigation.items) {
+    const id = validateUiMenuItem(item, executable, routes, sources, stateKeys, true);
+    if (ids.has(id)) throw new Error("UI navigation item is duplicated");
+    ids.add(id);
+    if (selectedKey != null && !("value" in item)) throw new Error("stateful UI navigation item requires a value");
+  }
+}
+
+function validateUiMenuItem(item, executable, routes, sources, stateKeys, navigation) {
+  rejectUnknownFields(item, new Set(contract.ui_runtime.menu_item_fields), "UI menu item");
+  optionalUiText(item.id, 128, { required: true, identifier: true });
+  optionalUiTemplate(item.label, 80, true);
+  validateTemplateReferences(item.label, stateKeys, sources);
+  for (const key of ["icon", "selected_icon"]) validateUiIcon(item[key]);
+  if (!navigation && item.selected_icon !== undefined) throw new Error("UI app bar action cannot have a selected icon");
+  const showAs = item.show_as === undefined ? "auto" : item.show_as;
+  if (!["auto", "always", "overflow"].includes(showAs)) throw new Error("UI menu presentation is invalid");
+  if (navigation && item.show_as !== undefined) throw new Error("UI navigation item cannot set show_as");
+  if ("value" in item) {
+    if (!navigation) throw new Error("UI app bar action cannot have a value");
+    validateUiJson(item.value, 0);
+  }
+  validateUiAction(item.action, executable, routes, sources, stateKeys, true);
+  return item.id;
 }
 
-function validateUiNode(node, depth, counter, executable, routes, sources, stateKeys) {
-  const nodeKeys = new Set(["id", "type", "props", "children", "action", "visible_when"]);
+function uiRuntimeAssetPaths(view) {
+  const result = new Set();
+  function visit(node) {
+    if (!node || typeof node !== "object" || Array.isArray(node)) return;
+    if (typeof node.props?.asset === "string") result.add(node.props.asset);
+    if (Array.isArray(node.children)) for (const child of node.children) visit(child);
+  }
+  visit(view);
+  return result;
+}
+
+function validateUiNode(node, depth, counter, executable, routes, sources, stateKeys, parentType) {
+  const nodeKeys = new Set(contract.ui_runtime.node_fields);
   rejectUnknownFields(node, nodeKeys, "UI component");
   counter.value += 1;
   if (depth > 12 || counter.value > 160) throw new Error("UI component tree is too large");
   if (!new Set(contract.ui_nodes).has(node.type)) throw new Error(`unknown UI component type: ${node.type}`);
-  if (node.id !== undefined && !UI_IDENTIFIER.test(String(node.id))) throw new Error("UI component id is invalid");
-  const props = node.props || {};
+  if (node.id != null && (typeof node.id !== "string" || !UI_IDENTIFIER.test(node.id))) throw new Error("UI component id is invalid");
+  const props = node.props === undefined ? {} : node.props;
   validateUiProps(node.type, props, sources, stateKeys);
   validateUiCondition(node.visible_when, stateKeys, sources);
+  if (node.action != null && !["surface", "card", "button", "chip"].includes(node.type)) {
+    throw new Error("UI action requires an interactive component");
+  }
   validateUiAction(node.action, executable, routes, sources, stateKeys);
-  const children = node.children || [];
+  const children = node.children === undefined ? [] : node.children;
   if (!Array.isArray(children) || children.length > 32) throw new Error("UI component children are invalid");
-  const leaves = new Set(["text", "icon", "divider", "spacer", "button", "chip", "metric", "progress", "calendar", "chart", "field", "select", "switch", "empty"]);
+  const leaves = new Set(["text", "icon", "image", "avatar", "divider", "spacer", "button", "chip", "metric", "progress", "calendar", "chart", "field", "select", "switch", "empty"]);
   if (leaves.has(node.type) && children.length) throw new Error("leaf UI component cannot have children");
   if (["list", "timeline"].includes(node.type) && children.length !== 1) throw new Error("list UI component requires one item template");
+  if (["positioned", "scroll", "padding", "center", "expanded", "badge"].includes(node.type) && children.length !== 1) throw new Error("UI component requires exactly one child");
+  if (node.type === "surface" && !children.length) throw new Error("surface UI component requires composed children");
+  if (node.type === "stack" && !children.some((child) => child?.type !== "positioned")) {
+    const boundedWidth = props.width !== undefined || props.max_width !== undefined;
+    const boundedHeight = props.height !== undefined || props.max_height !== undefined;
+    if (!boundedWidth || !boundedHeight) throw new Error("positioned-only stack requires bounded width and height");
+  }
+  if (node.type === "positioned" && parentType !== "stack") throw new Error("positioned UI component requires a stack parent");
+  if (node.type === "expanded" && !["row", "column"].includes(parentType)) throw new Error("expanded UI component requires a row or column parent");
   for (const child of children) {
     assertObject(child, "UI component child");
-    validateUiNode(child, depth + 1, counter, executable, routes, sources, stateKeys);
+    validateUiNode(child, depth + 1, counter, executable, routes, sources, stateKeys, node.type);
   }
 }
 
 function validateUiProps(nodeType, props, sources, stateKeys) {
-  const allowed = new Set([
-    "text", "title", "subtitle", "label", "supporting", "icon", "style", "tone", "align",
-    "max_lines", "spacing", "padding", "columns", "stack_at", "min_item_width", "size", "value",
-    "source", "empty_text", "limit", "state_key", "placeholder", "input_type", "options", "persist",
-    "selected", "dense", "chart_type", "x_key", "y_key", "date_key", "title_key", "show_legend", "full_width",
-  ]);
+  const allowed = new Set(contract.ui_runtime.prop_fields);
   rejectUnknownFields(props, allowed, "UI component props");
-  for (const key of ["text", "title", "subtitle", "label", "supporting", "placeholder", "empty_text", "value"]) {
+  const surfaceProps = new Set([
+    "spacing", "padding", "margin", "width", "height", "min_width", "max_width", "min_height", "max_height",
+    "alignment", "color", "background_color", "foreground_color", "border_color", "border_width",
+    "border_radius", "elevation", "opacity", "clip", "enabled", "tooltip", "semantic_label", "exclude_semantics",
+  ]);
+  if (nodeType === "surface") rejectUnknownFields(props, surfaceProps, "surface UI component props");
+  for (const key of ["text", "title", "subtitle", "label", "supporting", "placeholder", "empty_text", "value", "tooltip", "semantic_label"]) {
     if (props[key] !== undefined) {
       optionalUiTemplate(props[key], 1200, true);
       validateTemplateReferences(props[key], stateKeys, sources);
     }
   }
-  for (const key of ["icon", "style", "tone", "align", "input_type", "chart_type", "x_key", "y_key", "date_key", "title_key"]) {
+  for (const key of ["style", "tone", "align", "input_type", "chart_type", "x_key", "y_key", "date_key", "title_key"]) {
     if (props[key] !== undefined) optionalUiText(props[key], 80, { required: true, identifier: true });
   }
-  for (const key of ["max_lines", "spacing", "padding", "columns", "size", "limit"]) {
+  if (props.icon !== undefined) validateUiIcon(props.icon, true);
+  if (props.max_lines !== undefined && (!Number.isInteger(props.max_lines) || props.max_lines < 1 || props.max_lines > 100)) throw new Error("UI numeric property max_lines is invalid");
+  for (const key of ["columns", "size", "limit"]) {
     if (props[key] !== undefined && (!Number.isInteger(props[key]) || props[key] < 0 || props[key] > 100)) throw new Error(`UI numeric property ${key} is invalid`);
   }
+  if (props.spacing !== undefined) validateUiNumber(props.spacing, "UI spacing", 0, 128);
+  for (const key of ["padding", "margin"]) if (props[key] !== undefined) validateUiInsets(props[key], `UI ${key}`);
+  for (const key of ["width", "height", "min_width", "max_width", "min_height", "max_height"]) if (props[key] !== undefined) validateUiNumber(props[key], `UI ${key}`, 0, 4096);
+  for (const [minimum, maximum] of [["min_width", "max_width"], ["min_height", "max_height"]]) {
+    if (props[minimum] !== undefined && props[maximum] !== undefined && props[minimum] > props[maximum]) throw new Error("UI size constraints are invalid");
+  }
+  const alignments = new Set(["top_left", "top_center", "top_right", "center_left", "center", "center_right", "bottom_left", "bottom_center", "bottom_right"]);
+  if (props.alignment !== undefined && !alignments.has(props.alignment)) throw new Error("UI alignment is invalid");
+  if (props.main_axis_alignment !== undefined && !["start", "end", "center", "space_between", "space_around", "space_evenly"].includes(props.main_axis_alignment)) throw new Error("UI main-axis alignment is invalid");
+  if (props.cross_axis_alignment !== undefined && !["start", "end", "center", "stretch", "baseline"].includes(props.cross_axis_alignment)) throw new Error("UI cross-axis alignment is invalid");
+  if (props.main_axis_size !== undefined && !["min", "max"].includes(props.main_axis_size)) throw new Error("UI main-axis size is invalid");
+  for (const key of ["color", "background_color", "foreground_color", "border_color"]) if (props[key] !== undefined) validateUiColor(props[key], `UI ${key}`);
+  if (props.border_width !== undefined) validateUiNumber(props.border_width, "UI border width", 0, 8);
+  if (props.border_radius !== undefined) validateUiNumber(props.border_radius, "UI border radius", 0, 64);
+  if (props.elevation !== undefined) validateUiNumber(props.elevation, "UI elevation", 0, 24);
+  if (props.opacity !== undefined) validateUiNumber(props.opacity, "UI opacity", 0, 1);
+  if (props.aspect_ratio !== undefined) validateUiNumber(props.aspect_ratio, "UI aspect ratio", 0.1, 20);
+  if (props.flex !== undefined && (!Number.isInteger(props.flex) || props.flex < 1 || props.flex > 24)) throw new Error("UI flex is invalid");
+  for (const key of ["left", "top", "right", "bottom"]) if (props[key] !== undefined) validateUiNumber(props[key], `UI position ${key}`, -4096, 4096);
   if (props.stack_at !== undefined && (!Number.isInteger(props.stack_at) || props.stack_at < 0 || props.stack_at > 1200)) throw new Error("UI stack_at is invalid");
   if (props.min_item_width !== undefined && (!Number.isInteger(props.min_item_width) || props.min_item_width < 96 || props.min_item_width > 600)) throw new Error("UI min_item_width is invalid");
-  for (const key of ["persist", "selected", "dense", "show_legend", "full_width"]) if (props[key] !== undefined && typeof props[key] !== "boolean") throw new Error(`UI boolean property ${key} is invalid`);
+  for (const key of ["persist", "selected", "dense", "show_legend", "full_width", "exclude_semantics", "clip", "shrink_wrap", "enabled"]) if (props[key] !== undefined && typeof props[key] !== "boolean") throw new Error(`UI boolean property ${key} is invalid`);
+  if (props.fit !== undefined && !["contain", "cover", "fill", "fit_width", "fit_height", "none", "scale_down"].includes(props.fit)) throw new Error("UI image fit is invalid");
+  if (props.scroll_direction !== undefined && !["vertical", "horizontal"].includes(props.scroll_direction)) throw new Error("UI scroll direction is invalid");
+  if (["image", "avatar"].includes(nodeType)) validateUiImageSource(props, sources);
+  else if (["asset", "url", "fit"].some((key) => props[key] !== undefined)) throw new Error("image properties require an image or avatar component");
+  if (nodeType === "positioned" && !["left", "top", "right", "bottom"].some((key) => props[key] !== undefined)) throw new Error("positioned UI component requires an offset");
+  if (nodeType === "positioned" && (
+    ["left", "right", "width"].every((key) => props[key] !== undefined)
+    || ["top", "bottom", "height"].every((key) => props[key] !== undefined)
+  )) throw new Error("positioned UI component over-constrains an axis");
+  if (nodeType !== "positioned" && ["left", "top", "right", "bottom"].some((key) => props[key] !== undefined)) throw new Error("position offsets require a positioned UI component");
+  if (nodeType !== "expanded" && props.flex !== undefined) throw new Error("flex requires an expanded UI component");
+  if (nodeType !== "scroll" && ["scroll_direction", "shrink_wrap"].some((key) => props[key] !== undefined)) throw new Error("scroll properties require a scroll UI component");
   if (["list", "timeline", "calendar", "chart"].includes(nodeType)) {
     if (typeof props.source !== "string" || !UI_BINDING.test(props.source) || !props.source.startsWith("data.") || !sources.has(props.source.split(".")[1])) throw new Error("UI list source is invalid");
   }
-  if (nodeType === "chart" && !["bar", "line", "donut"].includes(props.chart_type || "bar")) throw new Error("UI chart type is invalid");
-  if (nodeType === "calendar" && props.state_key !== undefined && !stateKeys.has(props.state_key)) throw new Error("UI calendar state is unknown");
+  const chartType = props.chart_type === undefined ? "bar" : props.chart_type;
+  if (nodeType === "chart" && !["bar", "line", "donut"].includes(chartType)) throw new Error("UI chart type is invalid");
+  if (nodeType === "calendar" && props.state_key != null && !stateKeys.has(props.state_key)) throw new Error("UI calendar state is unknown");
   if (["field", "select", "switch"].includes(nodeType) && !stateKeys.has(props.state_key)) throw new Error("UI state field is unknown");
-  if (props.options !== undefined) {
+  if (props.options != null) {
     if (nodeType !== "select" || !Array.isArray(props.options) || props.options.length < 1 || props.options.length > 32) throw new Error("UI select options are invalid");
     for (const option of props.options) {
       if (!option || typeof option !== "object" || Array.isArray(option) || Object.keys(option).sort().join(",") !== "label,value") throw new Error("UI select option is invalid");
@@ -1315,8 +1477,47 @@ function validateUiProps(nodeType, props, sources, stateKeys) {
   }
 }
 
+function validateUiImageSource(props, sources) {
+  const supplied = ["asset", "url"].filter((key) => props[key] !== undefined);
+  if (supplied.length !== 1) throw new Error("image UI component requires exactly one safe source");
+  if (props.asset !== undefined) {
+    if (typeof props.asset !== "string" || props.asset.length > 240 || !UI_ASSET_PATH.test(props.asset) || props.asset.split("/").includes("..")) throw new Error("UI image asset is invalid");
+    return;
+  }
+  if (typeof props.url !== "string" || props.url.length > 2000) throw new Error("UI image URL binding is invalid");
+  const match = UI_SINGLE_TEMPLATE_BINDING.exec(props.url);
+  if (!match || !UI_BINDING.test(match[1].trim())) throw new Error("UI image URL must be a capability result binding");
+  const parts = match[1].trim().split(".");
+  if (!["data", "item"].includes(parts[0])) throw new Error("UI image URL binding is invalid");
+  if (parts[0] === "data" && (parts.length < 2 || !sources.has(parts[1]))) throw new Error("UI image data source is unknown");
+}
+
+function validateUiColor(value, label) {
+  if (typeof value !== "string" || (!UI_COLOR_TOKENS.has(value) && !UI_HEX_COLOR.test(value))) throw new Error(`${label} is invalid`);
+}
+
+function validateUiIcon(value, required = false) {
+  if (value == null && !required) return;
+  if (typeof value !== "string" || !UI_ICON_TOKENS.has(value)) throw new Error("UI icon token is invalid");
+}
+
+function validateUiNumber(value, label, minimum, maximum) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < minimum || value > maximum) throw new Error(`${label} is invalid`);
+}
+
+function validateUiInsets(value, label) {
+  if (typeof value === "number") {
+    validateUiNumber(value, label, 0, 128);
+    return;
+  }
+  assertObject(value, label);
+  const keys = Object.keys(value).sort().join(",");
+  if (!["all", "horizontal,vertical", "bottom,left,right,top"].includes(keys)) throw new Error(`${label} is invalid`);
+  for (const item of Object.values(value)) validateUiNumber(item, label, 0, 128);
+}
+
 function validateUiCondition(condition, stateKeys, sources) {
-  if (condition === undefined) return;
+  if (condition == null) return;
   rejectUnknownFields(condition, new Set(["path", "equals", "not_equals", "exists"]), "UI visibility condition");
   if (typeof condition.path !== "string" || !UI_BINDING.test(condition.path)) throw new Error("UI visibility path is invalid");
   validateKnownBinding(condition.path, stateKeys, sources);
@@ -1325,27 +1526,37 @@ function validateUiCondition(condition, stateKeys, sources) {
   if (checks[0] !== "exists") validateUiJson(condition[checks[0]], 0);
 }
 
-function validateUiAction(action, executable, routes, sources, stateKeys) {
-  if (action === undefined) return;
-  rejectUnknownFields(action, new Set(["type", "capability", "query", "arguments", "store", "target", "source", "values", "persist"]), "UI action");
+function validateUiAction(action, executable, routes, sources, stateKeys, required = false) {
+  if (action == null) {
+    if (required) throw new Error("UI action is required");
+    return;
+  }
+  rejectUnknownFields(action, new Set(contract.ui_runtime.action_fields), "UI action");
   if (!["invoke", "navigate", "set_state", "refresh", "back"].includes(action.type)) throw new Error("UI action type is invalid");
   if (action.type === "invoke") {
     if (!executable.has(action.capability)) throw new Error("UI action targets a non-executable capability");
     optionalUiTemplate(action.query, 2000);
     validateTemplateReferences(action.query, stateKeys, sources);
-    assertObject(action.arguments || {}, "UI action arguments");
-    validateUiBindingValue(action.arguments || {}, 0, stateKeys, sources);
-    if (action.store !== undefined && !sources.has(action.store)) throw new Error("UI action store is unknown");
+    const actionArguments = action.arguments === undefined ? {} : action.arguments;
+    assertObject(actionArguments, "UI action arguments");
+    validateUiBindingValue(actionArguments, 0, stateKeys, sources);
+    if (action.store != null && !sources.has(action.store)) throw new Error("UI action store is unknown");
   } else if (action.type === "navigate") {
     if (!routes.has(action.target)) throw new Error("UI navigation target is unknown");
+    const transition = action.transition === undefined ? "platform" : action.transition;
+    if (!["platform", "fade", "slide", "none"].includes(transition)) throw new Error("UI navigation transition is invalid");
+    const replace = action.replace === undefined ? false : action.replace;
+    if (typeof replace !== "boolean") throw new Error("UI navigation replacement is invalid");
   } else if (action.type === "set_state") {
     assertObject(action.values, "UI state action values");
     if (!Object.keys(action.values).length || Object.keys(action.values).some((key) => !stateKeys.has(key))) throw new Error("UI state action targets an unknown state key");
     validateUiBindingValue(action.values, 0, stateKeys, sources);
-    if (typeof (action.persist ?? false) !== "boolean") throw new Error("UI state persistence flag is invalid");
+    const persist = action.persist === undefined ? false : action.persist;
+    if (typeof persist !== "boolean") throw new Error("UI state persistence flag is invalid");
   } else if (action.type === "refresh") {
     if (!sources.has(action.source)) throw new Error("UI refresh source is unknown");
   } else if (Object.keys(action).length !== 1) throw new Error("back UI action cannot contain arguments");
+  if (action.type !== "navigate" && (action.transition !== undefined || action.replace !== undefined)) throw new Error("navigation options require a navigate UI action");
 }
 
 function validateUiBindingValue(value, depth, stateKeys, sources) {
@@ -1467,7 +1678,7 @@ function normalizeCapabilitySource(value, label) {
     throw new Error(`${label}.runtime must be an object`);
   }
   if (shorthand.length) {
-    const runtime = { ...(capability.runtime || {}) };
+    const runtime = { ...(capability.runtime === undefined ? {} : capability.runtime) };
     for (const name of shorthand) {
       if (Object.hasOwn(runtime, name) && !canonicalJson(runtime[name]).equals(canonicalJson(capability[name]))) {
         throw new Error(`${label}.${name} conflicts with ${label}.runtime.${name}`);