@topogram/cli 0.3.64 → 0.3.65

package/src/validator/projections/helpers.js

@@ -0,0 +1,87 @@
+// @ts-check
+
+import {
+  blockSymbolItems,
+  getFieldValue,
+  pushError,
+  symbolValues
+} from "../utils.js";
+import {
+  resolveShapeBaseFieldNames,
+  statementFieldNames
+} from "../model-helpers.js";
+
+/**
+ * @param {TopogramRegistry} registry
+ * @param {string} capabilityId
+ * @param {string} direction
+ * @returns {Set<string>}
+ */
+export function resolveCapabilityContractFields(registry, capabilityId, direction) {
+  const capability = registry.get(capabilityId);
+  if (!capability || capability.kind !== "capability") {
+    return new Set();
+  }
+
+  const refsField = direction === "input" ? getFieldValue(capability, "input") : getFieldValue(capability, "output");
+  const shapeId = symbolValues(refsField)[0];
+  if (!shapeId) {
+    return new Set();
+  }
+
+  const shape = registry.get(shapeId);
+  if (!shape || shape.kind !== "shape") {
+    return new Set();
+  }
+
+  const explicitFields = statementFieldNames(shape);
+  if (explicitFields.length > 0) {
+    return new Set(explicitFields);
+  }
+
+  return new Set(resolveShapeBaseFieldNames(shape, registry));
+}
+
+/**
+ * @param {TopogramRegistry} registry
+ * @param {string} capabilityId
+ * @returns {TopogramStatement | null}
+ */
+export function resolveCapabilityOutputShape(registry, capabilityId) {
+  const capability = registry.get(capabilityId);
+  if (!capability || capability.kind !== "capability") {
+    return null;
+  }
+
+  const shapeId = symbolValues(getFieldValue(capability, "output"))[0];
+  const shape = shapeId ? registry.get(shapeId) : null;
+  return shape?.kind === "shape" ? shape : null;
+}
+
+/**
+ * @param {string[]} tokens
+ * @param {number} startIndex
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramBlockEntry} entry
+ * @param {string} context
+ * @returns {Map<string, string>}
+ */
+export function parseUiDirectiveMap(tokens, startIndex, errors, statement, entry, context) {
+  const directives = new Map();
+
+  for (let i = startIndex; i < tokens.length; i += 2) {
+    const key = tokens[i];
+    const value = tokens[i + 1];
+    if (!key) {
+      continue;
+    }
+    if (!value) {
+      pushError(errors, `Projection ${statement.id} ${context} is missing a value for '${key}'`, entry.loc);
+      continue;
+    }
+    directives.set(key, value);
+  }
+
+  return directives;
+}

package/src/validator/projections/ui-helpers.js

@@ -0,0 +1,214 @@
+// @ts-check
+
+import {
+  blockEntries,
+  blockSymbolItems,
+  getFieldValue,
+  symbolValues
+} from "../utils.js";
+import {
+  resolveShapeBaseFieldNames,
+  statementFieldNames
+} from "../model-helpers.js";
+import {
+  parseUiDirectiveMap,
+  resolveCapabilityContractFields
+} from "./helpers.js";
+
+/**
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @returns {Map<string, TopogramBlockEntry>}
+ */
+export function collectProjectionUiScreens(statement, fieldMap) {
+  const screensField = fieldMap.get("screens")?.[0];
+  if (!screensField || screensField.value.type !== "block") {
+    return new Map();
+  }
+
+  const screens = new Map();
+  for (const entry of screensField.value.entries) {
+    const tokens = blockSymbolItems(entry).map((item) => item.value);
+    if (tokens[0] === "screen" && tokens[1]) {
+      screens.set(tokens[1], entry);
+    }
+  }
+  return screens;
+}
+
+/**
+ * @param {TopogramRegistry} registry
+ * @param {TopogramBlockEntry} screenEntry
+ * @param {TopogramStatement} statement
+ * @returns {Set<string>}
+ */
+
+export function resolveProjectionUiScreenFieldNames(registry, screenEntry, statement) {
+  const tokens = blockSymbolItems(screenEntry).map((item) => item.value);
+  const directives = parseUiDirectiveMap(tokens, 2, [], statement, screenEntry, "");
+  const kind = directives.get("kind");
+
+  if (kind === "form") {
+    const shapeId = directives.get("input_shape");
+    const shape = shapeId ? registry.get(shapeId) : null;
+    if (!shape || shape.kind !== "shape") {
+      return new Set();
+    }
+    const explicitFields = statementFieldNames(shape);
+    return new Set(explicitFields.length > 0 ? explicitFields : resolveShapeBaseFieldNames(shape, registry));
+  }
+
+  if (kind === "list") {
+    const loadCapabilityId = directives.get("load");
+    return loadCapabilityId ? resolveCapabilityContractFields(registry, loadCapabilityId, "input") : new Set();
+  }
+
+  if (kind === "detail" || kind === "job_status") {
+    const loadCapabilityId = directives.get("load");
+    return loadCapabilityId ? resolveCapabilityContractFields(registry, loadCapabilityId, "output") : new Set();
+  }
+
+  return new Set();
+}
+
+/**
+ * @param {TopogramStatement} statement
+ * @returns {Set<string>}
+ */
+
+export function screenIdsFromProjectionStatement(statement) {
+  const screens = new Set();
+  for (const entry of blockEntries(getFieldValue(statement, "screens"))) {
+    const tokens = blockSymbolItems(entry).map((item) => item.value);
+    if (tokens[0] === "screen" && tokens[1]) {
+      screens.add(tokens[1]);
+    }
+  }
+  return screens;
+}
+
+/**
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @param {TopogramRegistry} registry
+ * @returns {Set<string>}
+ */
+
+export function collectAvailableUiScreenIds(statement, fieldMap, registry) {
+  const available = new Set(collectProjectionUiScreens(statement, fieldMap).keys());
+  for (const targetId of symbolValues(getFieldValue(statement, "realizes"))) {
+    const target = registry.get(targetId);
+    if (target?.kind === "projection") {
+      for (const screenId of screenIdsFromProjectionStatement(target)) {
+        available.add(screenId);
+      }
+    }
+  }
+  return available;
+}
+
+/**
+ * @param {TopogramStatement} statement
+ * @returns {Set<string>}
+ */
+
+export function collectProjectionUiRegionKeys(statement) {
+  const keys = new Set();
+  for (const entry of blockEntries(getFieldValue(statement, "screen_regions"))) {
+    const tokens = blockSymbolItems(entry).map((item) => item.value);
+    if (tokens[0] === "screen" && tokens[1] && tokens[2] === "region" && tokens[3]) {
+      keys.add(`${tokens[1]}:${tokens[3]}`);
+    }
+  }
+  return keys;
+}
+
+/**
+ * @param {TopogramStatement} statement
+ * @param {TopogramRegistry} registry
+ * @returns {Set<string>}
+ */
+
+export function collectAvailableUiRegionKeys(statement, registry) {
+  const available = collectProjectionUiRegionKeys(statement);
+  for (const targetId of symbolValues(getFieldValue(statement, "realizes"))) {
+    const target = registry.get(targetId);
+    if (target?.kind === "projection") {
+      for (const key of collectProjectionUiRegionKeys(target)) {
+        available.add(key);
+      }
+    }
+  }
+  return available;
+}
+
+/**
+ * @param {TopogramStatement} statement
+ * @returns {Map<string, string>}
+ */
+
+export function collectProjectionUiRegionPatterns(statement) {
+  const patterns = new Map();
+  for (const entry of blockEntries(getFieldValue(statement, "screen_regions"))) {
+    const tokens = blockSymbolItems(entry).map((item) => item.value);
+    if (tokens[0] !== "screen" || !tokens[1] || tokens[2] !== "region" || !tokens[3]) {
+      continue;
+    }
+    for (let i = 4; i < tokens.length; i += 2) {
+      if (tokens[i] === "pattern" && tokens[i + 1]) {
+        patterns.set(`${tokens[1]}:${tokens[3]}`, tokens[i + 1]);
+      }
+    }
+  }
+  return patterns;
+}
+
+/**
+ * @param {TopogramStatement} statement
+ * @param {TopogramRegistry} registry
+ * @returns {Map<string, string>}
+ */
+
+export function collectAvailableUiRegionPatterns(statement, registry) {
+  const patterns = collectProjectionUiRegionPatterns(statement);
+  for (const targetId of symbolValues(getFieldValue(statement, "realizes"))) {
+    const target = registry.get(targetId);
+    if (target?.kind !== "projection") {
+      continue;
+    }
+    for (const [key, pattern] of collectProjectionUiRegionPatterns(target)) {
+      if (!patterns.has(key)) {
+        patterns.set(key, pattern);
+      }
+    }
+  }
+  return patterns;
+}
+
+/**
+ * @param {Map<string, string>} directives
+ * @param {string} key
+ * @returns {string}
+ */
+
+export function directiveValue(directives, key) {
+  return directives.get(key) || "";
+}
+
+export const SHARED_UI_SEMANTIC_BLOCKS = [
+  "screens",
+  "collection_views",
+  "screen_actions",
+  "visibility_rules",
+  "field_lookups",
+  "app_shell",
+  "navigation",
+  "screen_regions"
+];
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @returns {void}
+ */

package/src/validator/projections/ui-navigation.js

@@ -0,0 +1,344 @@
+// @ts-check
+
+import {
+  IDENTIFIER_PATTERN,
+  UI_APP_SHELL_KINDS,
+  UI_COLLECTION_PRESENTATIONS,
+  UI_DESIGN_ACCESSIBILITY_VALUES,
+  UI_DESIGN_ACTION_ROLES,
+  UI_DESIGN_COLOR_ROLES,
+  UI_DESIGN_DENSITIES,
+  UI_DESIGN_RADIUS_SCALES,
+  UI_DESIGN_TONES,
+  UI_DESIGN_TYPOGRAPHY_ROLES,
+  UI_NAVIGATION_PATTERNS,
+  UI_PATTERN_KINDS,
+  UI_REGION_KINDS,
+  UI_SCREEN_KINDS,
+  UI_STATE_KINDS,
+  UI_WINDOWING_MODES
+} from "../kinds.js";
+import {
+  blockSymbolItems,
+  getFieldValue,
+  pushError,
+  symbolValue,
+  symbolValues
+} from "../utils.js";
+import {
+  collectAvailableUiScreenIds,
+  directiveValue
+} from "./ui-helpers.js";
+import { parseUiDirectiveMap } from "./helpers.js";
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @param {TopogramRegistry} registry
+ * @returns {void}
+ */
+export function validateProjectionUiNavigation(errors, statement, fieldMap, registry) {
+  if (statement.kind !== "projection") {
+    return;
+  }
+
+  const navigationField = fieldMap.get("navigation")?.[0];
+  if (!navigationField || navigationField.value.type !== "block") {
+    return;
+  }
+
+  const availableScreens = collectAvailableUiScreenIds(statement, fieldMap, registry);
+  const groups = new Set();
+
+  for (const entry of navigationField.value.entries) {
+    const tokens = blockSymbolItems(entry).map((item) => item.value);
+    const [targetKind, targetId] = tokens;
+
+    if (targetKind === "group") {
+      if (!targetId || !IDENTIFIER_PATTERN.test(targetId)) {
+        pushError(errors, `Projection ${statement.id} navigation group entries must include a valid group id`, entry.loc);
+        continue;
+      }
+      groups.add(targetId);
+      const directives = parseUiDirectiveMap(tokens, 2, errors, statement, entry, `navigation group '${targetId}'`);
+      for (const key of directives.keys()) {
+        if (!["label", "placement", "icon", "order", "pattern"].includes(key)) {
+          pushError(errors, `Projection ${statement.id} navigation group '${targetId}' has unknown directive '${key}'`, entry.loc);
+        }
+      }
+      if (directives.has("placement") && !["primary", "secondary", "utility"].includes(directiveValue(directives, "placement"))) {
+        pushError(errors, `Projection ${statement.id} navigation group '${targetId}' has invalid placement '${directives.get("placement")}'`, entry.loc);
+      }
+      if (directives.has("pattern") && !UI_NAVIGATION_PATTERNS.has(directiveValue(directives, "pattern"))) {
+        pushError(errors, `Projection ${statement.id} navigation group '${targetId}' has invalid pattern '${directives.get("pattern")}'`, entry.loc);
+      }
+      continue;
+    }
+
+    if (targetKind === "screen") {
+      if (!availableScreens.has(targetId)) {
+        pushError(errors, `Projection ${statement.id} navigation references unknown screen '${targetId}'`, entry.loc);
+      }
+      const directives = parseUiDirectiveMap(tokens, 2, errors, statement, entry, `navigation screen '${targetId}'`);
+      for (const key of directives.keys()) {
+        if (!["group", "label", "order", "visible", "default", "breadcrumb", "sitemap", "placement", "pattern"].includes(key)) {
+          pushError(errors, `Projection ${statement.id} navigation screen '${targetId}' has unknown directive '${key}'`, entry.loc);
+        }
+      }
+      if (directives.has("visible") && !["true", "false"].includes(directiveValue(directives, "visible"))) {
+        pushError(errors, `Projection ${statement.id} navigation screen '${targetId}' has invalid visible '${directives.get("visible")}'`, entry.loc);
+      }
+      if (directives.has("default") && !["true", "false"].includes(directiveValue(directives, "default"))) {
+        pushError(errors, `Projection ${statement.id} navigation screen '${targetId}' has invalid default '${directives.get("default")}'`, entry.loc);
+      }
+      if (directives.has("placement") && !["primary", "secondary", "utility"].includes(directiveValue(directives, "placement"))) {
+        pushError(errors, `Projection ${statement.id} navigation screen '${targetId}' has invalid placement '${directives.get("placement")}'`, entry.loc);
+      }
+      if (directives.has("sitemap") && !["include", "exclude"].includes(directiveValue(directives, "sitemap"))) {
+        pushError(errors, `Projection ${statement.id} navigation screen '${targetId}' has invalid sitemap '${directives.get("sitemap")}'`, entry.loc);
+      }
+      if (directives.has("pattern") && !UI_NAVIGATION_PATTERNS.has(directiveValue(directives, "pattern"))) {
+        pushError(errors, `Projection ${statement.id} navigation screen '${targetId}' has invalid pattern '${directives.get("pattern")}'`, entry.loc);
+      }
+      const breadcrumb = directives.get("breadcrumb");
+      if (breadcrumb && breadcrumb !== "none" && !availableScreens.has(breadcrumb)) {
+        pushError(errors, `Projection ${statement.id} navigation screen '${targetId}' references unknown breadcrumb screen '${breadcrumb}'`, entry.loc);
+      }
+      continue;
+    }
+
+    pushError(errors, `Projection ${statement.id} navigation entries must start with 'group' or 'screen'`, entry.loc);
+  }
+
+  for (const entry of navigationField.value.entries) {
+    const tokens = blockSymbolItems(entry).map((item) => item.value);
+    if (tokens[0] !== "screen") {
+      continue;
+    }
+    const directives = parseUiDirectiveMap(tokens, 2, [], statement, entry, "");
+    if (directives.has("group") && !groups.has(directives.get("group"))) {
+      pushError(errors, `Projection ${statement.id} navigation screen '${tokens[1]}' references unknown group '${directives.get("group")}'`, entry.loc);
+    }
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @param {TopogramRegistry} registry
+ * @returns {void}
+ */
+
+export function validateProjectionUiScreenRegions(errors, statement, fieldMap, registry) {
+  if (statement.kind !== "projection") {
+    return;
+  }
+
+  const regionField = fieldMap.get("screen_regions")?.[0];
+  if (!regionField || regionField.value.type !== "block") {
+    return;
+  }
+
+  const availableScreens = collectAvailableUiScreenIds(statement, fieldMap, registry);
+  for (const entry of regionField.value.entries) {
+    const tokens = blockSymbolItems(entry).map((item) => item.value);
+    const [keyword, screenId, regionKeyword, regionName] = tokens;
+
+    if (keyword !== "screen") {
+      pushError(errors, `Projection ${statement.id} screen_regions entries must start with 'screen'`, entry.loc);
+      continue;
+    }
+    if (!availableScreens.has(screenId)) {
+      pushError(errors, `Projection ${statement.id} screen_regions references unknown screen '${screenId}'`, entry.loc);
+    }
+    if (regionKeyword !== "region") {
+      pushError(errors, `Projection ${statement.id} screen_regions for '${screenId}' must use 'region'`, entry.loc);
+    }
+    if (!UI_REGION_KINDS.has(regionName || "")) {
+      pushError(errors, `Projection ${statement.id} screen_regions for '${screenId}' has invalid region '${regionName}'`, entry.loc);
+    }
+
+    const directives = parseUiDirectiveMap(tokens, 4, errors, statement, entry, `screen_regions for '${screenId}'`);
+    for (const key of directives.keys()) {
+      if (!["pattern", "placement", "title", "state", "variant"].includes(key)) {
+        pushError(errors, `Projection ${statement.id} screen_regions for '${screenId}' has unknown directive '${key}'`, entry.loc);
+      }
+    }
+    if (directives.has("pattern") && !UI_PATTERN_KINDS.has(directiveValue(directives, "pattern"))) {
+      pushError(errors, `Projection ${statement.id} screen_regions for '${screenId}' has invalid pattern '${directives.get("pattern")}'`, entry.loc);
+    }
+    if (directives.has("placement") && !["primary", "secondary", "supporting"].includes(directiveValue(directives, "placement"))) {
+      pushError(errors, `Projection ${statement.id} screen_regions for '${screenId}' has invalid placement '${directives.get("placement")}'`, entry.loc);
+    }
+    if (directives.has("state") && !UI_STATE_KINDS.has(directiveValue(directives, "state"))) {
+      pushError(errors, `Projection ${statement.id} screen_regions for '${screenId}' has invalid state '${directives.get("state")}'`, entry.loc);
+    }
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @param {TopogramRegistry} registry
+ * @returns {void}
+ */
+
+export function validateProjectionUiRoutes(errors, statement, fieldMap, registry) {
+  if (statement.kind !== "projection") {
+    return;
+  }
+
+  const routesField = fieldMap.get("screen_routes")?.[0];
+  if (!routesField || routesField.value.type !== "block") {
+    return;
+  }
+
+  const availableScreens = collectAvailableUiScreenIds(statement, fieldMap, registry);
+  const seenPaths = new Set();
+  const projectionType = symbolValue(getFieldValue(statement, "type"));
+
+  for (const entry of routesField.value.entries) {
+    const tokens = blockSymbolItems(entry).map((item) => item.value);
+    const [keyword, screenId, pathKeyword, routePath] = tokens;
+
+    if (keyword !== "screen") {
+      pushError(errors, `Projection ${statement.id} screen_routes entries must start with 'screen'`, entry.loc);
+      continue;
+    }
+    if (!availableScreens.has(screenId)) {
+      pushError(errors, `Projection ${statement.id} screen_routes references unknown screen '${screenId}'`, entry.loc);
+    }
+    if (pathKeyword !== "path") {
+      pushError(errors, `Projection ${statement.id} screen_routes for '${screenId}' must use 'path'`, entry.loc);
+    }
+    if (!routePath) {
+      pushError(errors, `Projection ${statement.id} screen_routes for '${screenId}' must include a path`, entry.loc);
+      continue;
+    }
+    if ((projectionType === "web_surface" || projectionType === "ios_surface") && !routePath.startsWith("/")) {
+      pushError(errors, `Projection ${statement.id} screen_routes for '${screenId}' must use an absolute path`, entry.loc);
+    }
+    if (seenPaths.has(routePath)) {
+      pushError(errors, `Projection ${statement.id} screen_routes has duplicate path '${routePath}'`, entry.loc);
+    }
+    seenPaths.add(routePath);
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @param {TopogramRegistry} registry
+ * @param {string} surfaceBlockKey
+ * @param {string} expectedProjectionType
+ * @returns {void}
+ */
+
+export function validateProjectionUiSurfaceHints(errors, statement, fieldMap, registry, surfaceBlockKey, expectedProjectionType) {
+  if (statement.kind !== "projection") {
+    return;
+  }
+
+  const surfaceField = fieldMap.get(surfaceBlockKey)?.[0];
+  if (!surfaceField || surfaceField.value.type !== "block") {
+    return;
+  }
+
+  const projectionType = symbolValue(getFieldValue(statement, "type"));
+  if (projectionType !== expectedProjectionType) {
+    pushError(errors, `Projection ${statement.id} may only use '${surfaceBlockKey}' when projection type is '${expectedProjectionType}'`, surfaceField.loc);
+    return;
+  }
+
+  const availableScreens = collectAvailableUiScreenIds(statement, fieldMap, registry);
+  const realized = new Set(symbolValues(getFieldValue(statement, "realizes")));
+  for (const entry of surfaceField.value.entries) {
+    const tokens = blockSymbolItems(entry).map((item) => item.value);
+    const [targetKind, targetId, directive, value] = tokens;
+
+    if (targetKind === "screen") {
+      if (!availableScreens.has(targetId)) {
+        pushError(errors, `Projection ${statement.id} ${surfaceBlockKey} references unknown screen '${targetId}'`, entry.loc);
+      }
+      if (!["layout", "desktop_variant", "mobile_variant", "present", "shell", "collection", "breadcrumbs", "state_style"].includes(directive || "")) {
+        pushError(errors, `Projection ${statement.id} ${surfaceBlockKey} for screen '${targetId}' has unknown directive '${directive}'`, entry.loc);
+      }
+      if (directive === "desktop_variant" && !UI_COLLECTION_PRESENTATIONS.has(value || "")) {
+        pushError(errors, `Projection ${statement.id} ${surfaceBlockKey} for screen '${targetId}' has invalid desktop_variant '${value}'`, entry.loc);
+      }
+      if (directive === "mobile_variant" && !UI_COLLECTION_PRESENTATIONS.has(value || "")) {
+        pushError(errors, `Projection ${statement.id} ${surfaceBlockKey} for screen '${targetId}' has invalid mobile_variant '${value}'`, entry.loc);
+      }
+      if (directive === "collection" && !UI_COLLECTION_PRESENTATIONS.has(value || "")) {
+        pushError(errors, `Projection ${statement.id} ${surfaceBlockKey} for screen '${targetId}' has invalid collection '${value}'`, entry.loc);
+      }
+      if (directive === "shell" && !["topbar", "sidebar", "dual_nav", "workspace", "wizard", "bottom_tabs", "split_view", "menu_bar"].includes(value || "")) {
+        pushError(errors, `Projection ${statement.id} ${surfaceBlockKey} for screen '${targetId}' has invalid shell '${value}'`, entry.loc);
+      }
+      if (directive === "present" && !["page", "modal", "drawer", "sheet", "bottom_sheet", "popover"].includes(value || "")) {
+        pushError(errors, `Projection ${statement.id} ${surfaceBlockKey} for screen '${targetId}' has invalid present '${value}'`, entry.loc);
+      }
+      if (directive === "breadcrumbs" && !["visible", "hidden"].includes(value || "")) {
+        pushError(errors, `Projection ${statement.id} ${surfaceBlockKey} for screen '${targetId}' has invalid breadcrumbs '${value}'`, entry.loc);
+      }
+      if (directive === "state_style" && !["inline", "panel", "full_page"].includes(value || "")) {
+        pushError(errors, `Projection ${statement.id} ${surfaceBlockKey} for screen '${targetId}' has invalid state_style '${value}'`, entry.loc);
+      }
+      continue;
+    }
+
+    if (targetKind === "action") {
+      const capability = registry.get(targetId);
+      if (!capability) {
+        pushError(errors, `Projection ${statement.id} ${surfaceBlockKey} references missing capability '${targetId}'`, entry.loc);
+      } else if (capability.kind !== "capability") {
+        pushError(errors, `Projection ${statement.id} ${surfaceBlockKey} must reference a capability for action '${targetId}', found ${capability.kind} '${capability.id}'`, entry.loc);
+      } else if (!realized.has(targetId)) {
+        pushError(errors, `Projection ${statement.id} ${surfaceBlockKey} action '${targetId}' must also appear in 'realizes'`, entry.loc);
+      }
+      if (!["confirm", "present", "placement"].includes(directive || "")) {
+        pushError(errors, `Projection ${statement.id} ${surfaceBlockKey} for action '${targetId}' has unknown directive '${directive}'`, entry.loc);
+      }
+      if (directive === "confirm" && !["modal", "inline", "sheet", "bottom_sheet", "popover"].includes(value || "")) {
+        pushError(errors, `Projection ${statement.id} ${surfaceBlockKey} for action '${targetId}' has invalid confirm mode '${value}'`, entry.loc);
+      }
+      if (directive === "present" && !["button", "menu_item", "split_button", "bulk_action", "drawer", "sheet", "bottom_sheet", "fab", "popover"].includes(value || "")) {
+        pushError(errors, `Projection ${statement.id} ${surfaceBlockKey} for action '${targetId}' has invalid present mode '${value}'`, entry.loc);
+      }
+      if (directive === "placement" && !["toolbar", "menu", "bulk", "inline", "footer"].includes(value || "")) {
+        pushError(errors, `Projection ${statement.id} ${surfaceBlockKey} for action '${targetId}' has invalid placement '${value}'`, entry.loc);
+      }
+      continue;
+    }
+
+    pushError(errors, `Projection ${statement.id} ${surfaceBlockKey} entries must start with 'screen' or 'action'`, entry.loc);
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @param {TopogramRegistry} registry
+ * @returns {void}
+ */
+
+export function validateProjectionUiWeb(errors, statement, fieldMap, registry) {
+  validateProjectionUiSurfaceHints(errors, statement, fieldMap, registry, "web_hints", "web_surface");
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @param {TopogramRegistry} registry
+ * @returns {void}
+ */
+
+export function validateProjectionUiIos(errors, statement, fieldMap, registry) {
+  validateProjectionUiSurfaceHints(errors, statement, fieldMap, registry, "ios_hints", "ios_surface");
+}