// SOMA 页面声明校验器：AI 生成统一声明后的质量闸门。
//
// 校验维度：
// - 注入面安全扫描（禁用标签 / 内联事件属性 / 伪协议，与发布管线同一把尺子）；
// - canonical _ui.yaml 结构合法（bind/show、内嵌事件与四动词 Pipeline）；
// - ui 引用的锚点在 html 中存在（组件内部锚点不许被页面引用——AI 常见错误）；
// - 组件实例：组件名在目录内、props ⊆ 契约、required props 齐全、必填插槽有内容；
// - emit 订阅：实例锚点上的非 DOM 事件必须匹配契约 emit；
// - 普通锚点订阅：事件名必须在 DOM 事件名单里（普通锚点没有 emit 可订阅）。
//
// 说明：html 检查基于正则扫描（服务端无 DOM），是保守近似——宁可放过布局细节，
// 绝不放过契约违约。发现的问题以中文清单返回，供生成器自修复重试时回喂模型。

import yaml from 'js-yaml';
import { compilePageDeclaration } from 'soma-core/server/page-declaration';
import { scanDeclarationSafety } from 'soma-core/server/declaration-safety';
import { TAILWIND_PAGE_CLASSES, TAILWIND_PAGE_VOCABULARY } from './TailwindPageVocabulary';

/** 与 soma-core C11 对齐的目录侧几何族值域；运行时值由目录条目携带。 */
export type SomaGeometryFamily = 'control' | 'surface' | 'message' | 'data' | 'overlay' | 'layout' | 'display';

export interface PageCatalogProp {
  name: string;
  required: boolean;
  type?: string;
  /**
   * 目录是 Host 运行时契约的投影；这些说明字段不参与 Tailwind 页面生成，
   * 但橱窗和审查页须能如实展示原契约，不能在 soma-ai 边界被截断。
   */
  values?: Array<string | number>;
  mode?: 'oneway' | 'model' | string;
  default?: unknown;
  desc?: string;
}

export interface PageCatalogEmit {
  name: string;
  /** 原始目录的 emit payload 字段；Host 可在自己的只读 API 中再投影为字段名。 */
  payload?: Array<{ name: string; type?: string; desc?: string }>;
  desc?: string;
}

export interface PageCatalogSlot {
  name: string;
  required: boolean;
  desc?: string;
}

export interface PageCatalogEntry {
  name: string;
  /** 组件主几何族；旧目录条目缺省时保留声明链兼容，真实 catalog 均已补齐。 */
  geometry?: SomaGeometryFamily;
  layer?: string;
  props: PageCatalogProp[];
  emits: PageCatalogEmit[];
  slots: PageCatalogSlot[];
}

export interface PageDeclarations {
  html: string;
  uiYaml: string;
  eventYaml: string;
  styleYaml?: string;
  /** 退役侧车字段只为 API 边界给出明确拒绝；合法声明必须为空。 */
  dataYaml?: string;
}

/**
 * BlueprintCompiler 产物根节点的来源标记（属性名），只有取值 `"true"` 才算数。
 *
 * 全仓只此一份：编译器写它，结构闸门与声明 lint 用同一个 `hasGeneratedPageMarker` 认它，
 * 两处判据不会再各写一条正则、各自漂移。
 */
export const GENERATED_PAGE_MARKER = 'data-soma-ai-tailwind-page';

interface HtmlComponentHost {
  id?: string;
  name: string;
}

/** HTML 属性支持双引号、单引号与无引号；所有声明扫描必须共用这一口径。 */
function readHtmlAttribute(tag: string, name: string): string | undefined {
  const match = tag.match(new RegExp(
    `\\b${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s"'=<>]+))`,
    'i',
  ));
  return match ? (match[1] ?? match[2] ?? match[3]) : undefined;
}

function collectComponentHosts(html: string): HtmlComponentHost[] {
  const result: HtmlComponentHost[] = [];
  for (const match of html.matchAll(/<[a-z][^>]*>/gi)) {
    const name = readHtmlAttribute(match[0], 'data-soma-component');
    if (!name) continue;
    const id = readHtmlAttribute(match[0], 'data-soma-id');
    result.push({
      ...(id ? { id } : {}),
      name,
    });
  }
  return result;
}

/**
 * 按组件实例归属收集宿主提供的插槽。
 *
 * 不能用全文 includes：页面里任意一个 Card.content 会让另一个缺 content 的 StatePanel
 * 被误判为合格。这里用轻量标签栈把 data-soma-slot 归给最近的组件祖先；不承担完整 HTML
 * 解析，只守住组件投影所需的父子边界。
 */
function collectProvidedSlots(html: string): Map<string, Set<string>> {
  const provided = new Map<string, Set<string>>();
  const stack: Array<{ tag: string; componentId?: string }> = [];
  const voidTags = new Set([
    'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta',
    'source', 'track', 'wbr',
  ]);

  for (const match of html.matchAll(/<!--[^]*?-->|<\/?([a-z][\w:-]*)\b[^>]*>/gi)) {
    const token = match[0];
    if (token.startsWith('<!--')) continue;
    const tag = (match[1] ?? '').toLowerCase();
    if (!tag) continue;

    if (/^<\//.test(token)) {
      for (let index = stack.length - 1; index >= 0; index -= 1) {
        if (stack[index].tag === tag) {
          stack.splice(index);
          break;
        }
      }
      continue;
    }

    const owner = [...stack].reverse().find((entry) => entry.componentId)?.componentId;
    const slotName = readHtmlAttribute(token, 'data-soma-slot');
    if (owner && slotName) {
      const names = provided.get(owner) ?? new Set<string>();
      names.add(slotName);
      provided.set(owner, names);
    }

    const componentId = readHtmlAttribute(token, 'data-soma-component')
      ? readHtmlAttribute(token, 'data-soma-id')
      : undefined;
    if (componentId && !provided.has(componentId)) provided.set(componentId, new Set());
    if (!/\/\s*>$/.test(token) && !voidTags.has(tag)) stack.push({ tag, componentId });
  }
  return provided;
}

/** 带 `GENERATED_PAGE_MARKER="true"` 的开标签（引号口径与 readHtmlAttribute 一致）。 */
function generatedPageRoots(html: string): RegExpMatchArray[] {
  return [...html.matchAll(/<([a-z][\w:-]*)\b[^>]*>/gi)]
    .filter((match) => readHtmlAttribute(match[0], GENERATED_PAGE_MARKER) === 'true');
}

/** 声明是否自称 BlueprintCompiler 生成页。`="false"` 或只写属性名都不算。 */
export function hasGeneratedPageMarker(html: string): boolean {
  return generatedPageRoots(html).length > 0;
}

/**
 * BlueprintCompiler 的产物有一个明确的 Tailwind 页面边界。这里不把 Tailwind
 * 本身当作安全规则，而是防止页面在迁移后悄悄退回旧的 soma-ui 包壳或半成品结构。
 */
function tailwindPageContractIssues(html: string): string[] {
  const roots = generatedPageRoots(html);
  if (roots.length === 0) return [];

  const issues: string[] = [];
  if (roots.length !== 1) {
    issues.push(`[Tailwind 页面] 只能有一个 ${GENERATED_PAGE_MARKER}="true" 根节点`);
    return issues;
  }
  const [root] = roots;
  if (root[1]?.toLowerCase() !== 'main') {
    issues.push('[Tailwind 页面] 根节点必须是语义化 <main>');
  }
  const skeleton = readHtmlAttribute(root[0], 'data-soma-ai-skeleton');
  if (!skeleton || !TAILWIND_PAGE_VOCABULARY.skeletons.includes(skeleton as never)) {
    issues.push(`[Tailwind 页面] skeleton 必须是 ${TAILWIND_PAGE_VOCABULARY.skeletons.join(' / ')}`);
  } else {
    const tokens = new Set((readHtmlAttribute(root[0], 'class') ?? '').split(/\s+/).filter(Boolean));
    const required = TAILWIND_PAGE_CLASSES.root[skeleton as keyof typeof TAILWIND_PAGE_CLASSES.root]
      .split(/\s+/);
    if (!required.every((token) => tokens.has(token))) {
      issues.push('[Tailwind 页面] 根节点缺少受控 Tailwind 骨架 class，必须由 BlueprintCompiler 生成');
    }
  }
  if (!/\bdata-soma-id\s*=\s*(?:"page_title"|'page_title'|page_title\b)/.test(html)) {
    issues.push('[Tailwind 页面] 缺少 page_title 锚点');
  }
  if (collectComponentHosts(html).length > 0) {
    issues.push('[Tailwind 页面] 直出页面不得混入 data-soma-component；组件目录只用于语义和契约校验');
  }
  return issues;
}

/**
 * DOM 事件名单：组件实例锚点上的订阅据此区分"DOM 事件"与"契约 emit"；普通锚点上的订阅
 * 只能用名单里的事件。
 *
 * 必须与 soma-core `core/client/parser/pipeline-parser.ts` 的 `VALID_DOM_EVENTS` 逐项一致——
 * 那份名单与 `isKnownDomEvent` 不在 soma-core 任何公开子路径上导出，soma-ai 只能经公开
 * 子路径依赖 soma-core，所以这里手工对齐；core 增删事件时同步改这里。
 */
const DOM_EVENTS = new Set([
  'click', 'dblclick', 'input', 'change', 'blur',
  'focus', 'focusin', 'focusout', 'mouseenter', 'mouseleave', 'submit',
  'keydown', 'keyup', 'scroll',
]);

/** 模型写悬停交互时常用的名单外事件名（hover 不是 DOM 事件，是高频幻觉） */
const HOVER_EVENT_NAMES = new Set([
  'hover', 'mouseover', 'mouseout', 'pointerover', 'pointerout', 'pointerenter', 'pointerleave',
]);
const PRESS_EVENT_NAMES = new Set(['mousedown', 'mouseup', 'pointerdown', 'pointerup', 'touchstart', 'touchend']);
const TEXT_ENTRY_EVENT_NAMES = new Set(['beforeinput', 'compositionstart', 'compositionupdate', 'compositionend']);

/**
 * 普通锚点上名单外事件的替代写法，回喂模型改写用。
 *
 * 悬停、按下 / 抬起、keypress、输入法几组沿用 soma-core 运行时告警（pipeline-parser 的
 * UNLISTED_DOM_EVENT_HINTS）的替代写法；那份表不在公开子路径上导出，这里只收模型最常写的几组。
 * 其余名字 core 建议自己封装组件，生成的页面只能用目录里的组件，所以改说订阅目录组件的契约 emit。
 * Tooltip 只在用得上时才提：目录里没有它，或 AI Tailwind 页面禁止混入组件时，提了只会换来
 * 下一轮的另一条问题。
 */
function unlistedAnchorEventAlternative(eventName: string, tooltipUsable: boolean): string {
  if (HOVER_EVENT_NAMES.has(eventName)) {
    return '悬停样式用 Style transitions 的 hover；悬停才出现的提示或面板用 click、focusin / focusout'
      + (tooltipUsable ? '，或 Tooltip 组件' : '');
  }
  if (PRESS_EVENT_NAMES.has(eventName)) return '按下 / 抬起改用 click';
  if (eventName === 'keypress') return '改用 keydown（按键用修饰符，如 id.keydown.enter）';
  if (TEXT_ENTRY_EVENT_NAMES.has(eventName)) return '改用 input';
  return '改用上面的 DOM 事件；拖拽、右键、滚轮这类名单覆盖不了的交互交给组件目录里的组件，订阅它的契约 emit';
}

/**
 * 生成页允许的 Pipeline 动词。
 *
 * 刻意少一个 `ACTION`：它取的是宿主 bootstrap 注册表里的具名动作，生成的页面没有宿主代码，
 * 写出来必然在挂载时报"未注册的动作"。这不是与 core 的 `VALID_TYPES` 失配，是本闸门按
 * 生成链能力收窄的一档。
 */
const PIPELINE_VERBS = new Set(['NAV_STATIC', 'NAV_ACTION', 'UI_REFRESH', 'UI_INTERACT']);

/**
 * 动词缺省（REQ-005 F7.1，core 的 `IMPLICIT_REFRESH_FUNC_PATH`）：首段是小写起头、
 * 至少两段的 funcPath 时，引擎按 `UI_REFRESH` 补齐。闸门跟着认，否则一条引擎跑得动的声明
 * 会被判成"动词不合法"——闸门比引擎严不是安全，是把合法页面挡在门外。
 */
const IMPLICIT_REFRESH_FUNC_PATH = /^[a-z][A-Za-z0-9_]*(?:\.[A-Za-z0-9_]+)+$/;

/** UI_INTERACT 的具名动作段（REQ-005 F7.2）：`action:open` 与位置式第 3 槽等价 */
const ACTION_SEGMENT_PREFIX = 'action:';

/** YAML 解析失败回喂模型时的纠正提示（实测高频根因：flow 映射里不加引号的逗号值） */
const YAML_PARSE_HINT = '（常见原因：含逗号 / 冒号 / ¥ / % 的字符串值必须加双引号，'
  + '尤其 flow 式 { } 内——如 amount: "¥1,280.00"；请修正缩进与引号后重新输出）';

export interface ValidateDeclarationsOptions {
  /**
   * 本次生成授权绑定的接口路径。给了就核对统一声明编译出的数据对象——
   * 绑了清单外的接口在这里变成**问题清单回喂模型自修复**,而不是等到落库时
   * 被注册中心的取数白名单硬拒(那时用户看到的只是一次失败,没有修复机会)。
   */
  allowedApiPaths?: readonly string[];
  /**
   * 是否校验 AI Blueprint 的 Tailwind 页面边界。生成链默认启用；普通 Host
   * 存量声明巡检可显式关闭，但 canonical 编译、安全与组件契约检查仍会执行。
   */
  enforceStructureGate?: boolean;
}

export function validatePageDeclarations(
  decl: PageDeclarations,
  catalog: PageCatalogEntry[],
  options: ValidateDeclarationsOptions = {},
): string[] {
  // 注入面扫描先跑：坏声明在生成链里就该被打回自修复，而不是等到发布时才被仓库拒绝
  const issues: string[] = scanDeclarationSafety(decl);
  let runtimeAssets: ReturnType<typeof compilePageDeclaration>['runtimeAssets'] | null = null;
  /** 声明了 window: 段的数据对象名（data_object 只能指向它们）；编译失败时为 null = 跳过这一层 */
  let windowObjects: Set<string> | null = null;
  try {
    // soma-ai 不装配任何组件库的 OOUI 引擎。若 Host 自己提交带 `ooui:`
    // 的旧声明，Host 必须在其启动边界完成装配；这里会把缺失能力如实报为 DSL 错误。
    const compiled = compilePageDeclaration({
      html: decl.html,
      uiYaml: decl.uiYaml,
      ...(decl.eventYaml ? { eventYaml: decl.eventYaml } : {}),
      ...(decl.styleYaml ? { styleYaml: decl.styleYaml } : {}),
      ...(decl.dataYaml ? { dataYaml: decl.dataYaml } : {}),
    });
    runtimeAssets = compiled.runtimeAssets;
    windowObjects = new Set(
      Object.entries(compiled.dataConfig?.objects ?? {})
        .filter(([, object]) => object.window !== undefined)
        .map(([name]) => name),
    );
    issues.push(...checkDataBindings(compiled.dataConfig, options.allowedApiPaths));
  } catch (error) {
    issues.push(`[dsl] SOMA DSL 声明编译失败：${(error as Error).message}${YAML_PARSE_HINT}`);
  }
  const byName = new Map(catalog.map((entry) => [entry.name, entry]));

  // ── html 扫描 ──
  const anchors = new Set<string>();
  for (const match of decl.html.matchAll(/<[a-z][^>]*>/gi)) {
    const anchor = readHtmlAttribute(match[0], 'data-soma-id');
    if (anchor) anchors.add(anchor);
  }

  const instances = new Map<string, string>(); // 实例id → 组件名
  const componentHosts = collectComponentHosts(decl.html);
  for (const host of componentHosts) {
    if (!host.id) {
      const name = host.name;
      issues.push(`[html] 组件 "${name}" 的宿主元素缺少 data-soma-id`);
      continue;
    }
    instances.set(host.id, host.name);
    if (!byName.has(host.name)) {
      issues.push(`[html] 组件 "${host.name}" 不在组件目录中（可用：${[...byName.keys()].join(', ')}）`);
    }
  }

  // 只校验明确标记为 AI Tailwind 页面的一条产物契约；历史 Host 声明继续只过
  // canonical DSL、安全和组件契约门，避免把 Host 的 UI 技术选型硬塞进 soma-ai。
  if (options.enforceStructureGate !== false) {
    issues.push(...tailwindPageContractIssues(decl.html));
  }

  // 必填插槽必须由当前组件实例自己提供，不能借页面里另一个组件的同名插槽蒙混过关。
  const providedSlots = collectProvidedSlots(decl.html);
  for (const [instanceId, name] of instances) {
    const entry = byName.get(name);
    if (!entry) continue;
    for (const slot of entry.slots) {
      if (slot.required && !providedSlots.get(instanceId)?.has(slot.name)) {
        issues.push(`[html] 组件实例 "${instanceId}"（${name}）缺少必填插槽 <template data-soma-slot="${slot.name}">`);
      }
    }
  }

  if (!runtimeAssets) return issues;

  // ── 编译后的运行时 UI 资产 ──
  let uiRoot: Record<string, unknown> | null = null;
  try {
    const parsed = yaml.load(runtimeAssets.uiYaml);
    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
      issues.push('[ui] ui.yaml 必须是对象');
    } else {
      uiRoot = parsed as Record<string, unknown>;
    }
  } catch (error) {
    issues.push(`[ui] ui.yaml 解析失败：${(error as Error).message}${YAML_PARSE_HINT}`);
  }

  const instanceProps = new Map<string, Record<string, unknown>>();
  if (uiRoot) {
    const bind = uiRoot.bind as { obj?: unknown; var?: unknown } | undefined;
    if (!bind || typeof bind.obj !== 'string' || typeof bind.var !== 'string') {
      issues.push('[ui] 缺少顶层 bind: { obj, var }');
    }
    const show = uiRoot.show;
    if (!show || typeof show !== 'object') {
      issues.push('[ui] 缺少顶层 show 映射');
    } else {
      walkShow(show as Record<string, unknown>, anchors, instanceProps, issues);
    }
  }

  // 组件 props 契约校验
  for (const [instanceId, name] of instances) {
    const entry = byName.get(name);
    if (!entry) continue;
    const declared = instanceProps.get(instanceId) ?? {};
    const legal = new Set(entry.props.map((prop) => prop.name));
    for (const key of Object.keys(declared)) {
      if (!legal.has(key)) {
        issues.push(`[ui] 实例 "${instanceId}"（${name}）传入了契约不存在的 prop "${key}"（可用：${[...legal].join(', ')}）`);
      }
    }
    for (const prop of entry.props) {
      if (prop.required && !(prop.name in declared)) {
        issues.push(`[ui] 实例 "${instanceId}"（${name}）缺少必填 prop "${prop.name}"`);
      }
    }
    // 数据窗口消费面（REQ-011 F-37）：data_object 必须指向声明了 window: 的数据对象，
    // 且不与受控 rows 同给——两者同给时窗口赢，rows 被静默忽略，模型会以为演示数据在生效
    if (legal.has('data_object') && typeof declared.data_object === 'string' && declared.data_object.trim() !== '') {
      const target = declared.data_object.trim();
      if (windowObjects !== null && !windowObjects.has(target)) {
        issues.push(
          `[data] 实例 "${instanceId}"（${name}）的 data_object 指向 "${target}"，但它不是本页声明了 window 段的数据对象`
            + `（可用：${[...windowObjects].join(', ') || '无——请在 data 段为该对象加 window'}）`,
        );
      }
      if ('rows' in declared) {
        issues.push(`[data] 实例 "${instanceId}"（${name}）同时给了 data_object 与 rows——二选一：窗口形态下行由引擎持有，rows 会被忽略`);
      }
    }
  }

  // ── 编译后的运行时事件资产 ──
  // 结构闸门对 AI Tailwind 页面禁止混入组件，那里不能把 Tooltip 当替代写法推给模型
  const tooltipUsable = byName.has('Tooltip')
    && !(options.enforceStructureGate !== false && hasGeneratedPageMarker(decl.html));
  try {
    const parsed = runtimeAssets.eventYaml.trim() ? yaml.load(runtimeAssets.eventYaml) : {};
    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
      walkEvents(parsed as Record<string, unknown>, instances, byName, tooltipUsable, issues);
    } else if (parsed !== null && parsed !== undefined) {
      issues.push('[event] event.yaml 必须是对象');
    }
  } catch (error) {
    issues.push(`[event] event.yaml 解析失败：${(error as Error).message}${YAML_PARSE_HINT}`);
  }

  return issues;
}

/** show 对象值的合法键白名单（与运行端 UiConfigParser 对齐） */
// canonical 平铺语法会把 `anchor` + `anchor.when` / `anchor.class` 编译成
// `{ text, when, class }`；这里校验的是编译后的运行时资产，必须接受运行时
// ExtendedShowValue 的完整键集。源声明里直接写嵌套 text/class 仍会在唯一编译入口被拒。
const SHOW_OBJECT_KEYS = new Set(['text', 'model', 'when', 'class', 'bind', 'show', 'props']);

/** 幻觉语法的纠正提示：回喂给模型时不只报错，还要告诉它允许的形态是什么 */
const SHOW_FORM_HINT = 'show 值只允许：绑定路径字符串（page.xxx / 行变量.xxx）'
  + ' / { model: 路径 } / { when: 路径或"!路径" } / { props: {…} }'
  + ' / { bind: { obj: page.列表, var: 行变量 }, show: {…} }'
  + '——不存在 /text、text、html、value、content 等键';

function walkShow(
  show: Record<string, unknown>,
  anchors: Set<string>,
  instanceProps: Map<string, Record<string, unknown>>,
  issues: string[],
): void {
  for (const [rawKey, value] of Object.entries(show)) {
    const anchorId = rawKey.split('@')[0];
    if (!anchors.has(anchorId)) {
      issues.push(`[ui] show 键 "${rawKey}" 对应的锚点 data-soma-id="${anchorId}" 在 html 中不存在（组件内部锚点不允许被页面引用）`);
    }

    if (typeof value === 'string') {
      continue;
    }
    if (!value || typeof value !== 'object' || Array.isArray(value)) {
      // 数字 / 布尔 / null / 数组都不是合法 show 值形态
      issues.push(`[ui] show."${rawKey}" 的值形态非法——${SHOW_FORM_HINT}`);
      continue;
    }
    const obj = value as Record<string, unknown>;

    // 白名单键校验：模型幻觉（如 {"/text": …}、{"value": …}）在闸门就拦下并给纠正提示，
    // 不放到渲染端 UiConfigParser 才炸
    const unknownKeys = Object.keys(obj).filter((key) => !SHOW_OBJECT_KEYS.has(key));
    if (unknownKeys.length > 0) {
      issues.push(`[ui] show."${rawKey}" 使用了不存在的键 ${unknownKeys.map((key) => `"${key}"`).join('、')}——${SHOW_FORM_HINT}`);
    }

    if (obj.props && typeof obj.props === 'object' && !Array.isArray(obj.props)) {
      instanceProps.set(anchorId, obj.props as Record<string, unknown>);
    }
    if (obj.show && typeof obj.show === 'object' && !Array.isArray(obj.show)) {
      walkShow(obj.show as Record<string, unknown>, anchors, instanceProps, issues);
    }
  }
}

function walkEvents(
  events: Record<string, unknown>,
  instances: Map<string, string>,
  byName: Map<string, PageCatalogEntry>,
  tooltipUsable: boolean,
  issues: string[],
): void {
  for (const [selector, value] of Object.entries(events)) {
    // timers / triggers 是事件文件的顶层块(DSL 语法全书 §5),值是条目数组而非
    // Pipeline 字符串——它们由引擎另行解析,这里只做存在性放行,不按选择器规则量。
    if (selector === 'timers' || selector === 'triggers') {
      if (!Array.isArray(value)) {
        issues.push(`[event] "${selector}" 块的值必须是条目数组`);
      }
      continue;
    }
    if (value && typeof value === 'object' && !Array.isArray(value)) {
      // 列表作用域嵌套
      walkEvents(value as Record<string, unknown>, instances, byName, tooltipUsable, issues);
      continue;
    }
    if (typeof value !== 'string') {
      issues.push(`[event] "${selector}" 的值必须是 Pipeline 字符串`);
      continue;
    }

    const parts = selector.split('.');
    if (parts.length < 2 || parts.length > 3) {
      issues.push(`[event] 选择器 "${selector}" 格式错误，应为 id.event 或 id.event.modifier`);
      continue;
    }
    const [somaId, eventName] = parts;

    const rawSegments = value.split('|').map((part) => part.trim());
    // 具名段先摘走，剩下的才是位置段——否则 `UI_INTERACT | dialog | action:show` 的动作
    // 落不进第 3 槽，幻觉动作就从闸门底下溜过去了（核对时的实测：整条动作校验被跳过）
    const namedAction = rawSegments
      .slice(1)
      .find((part) => part.startsWith(ACTION_SEGMENT_PREFIX))
      ?.slice(ACTION_SEGMENT_PREFIX.length)
      .trim();
    const segments = rawSegments.filter(
      (part, index) => index === 0 || !part.startsWith(ACTION_SEGMENT_PREFIX),
    );
    // 动词缺省：首段是 funcPath 就按 UI_REFRESH 读，槽位跟着右移一格（与 core 同一条判别）
    const implicitRefresh = !PIPELINE_VERBS.has(segments[0])
      && IMPLICIT_REFRESH_FUNC_PATH.test(segments[0] ?? '');
    if (implicitRefresh) {
      segments.unshift('UI_REFRESH');
    }
    const verb = segments[0];
    if (!PIPELINE_VERBS.has(verb)) {
      issues.push(`[event] "${selector}" 的动词 "${verb}" 不合法（四动词：${[...PIPELINE_VERBS].join(' | ')}；`
        + '省略动词按 UI_REFRESH 处理，但首段须是小写起头、至少两段的 funcPath，如 page.save）');
    }
    // UI_INTERACT 动作白名单：show/hide 这类幻觉动作在闸门就拦下并附纠正提示。
    // 本表比 core 的 VALID_ACTIONS 窄（core 还有 focus / scroll_to / select），是生成链的刻意收窄。
    if (verb === 'UI_INTERACT') {
      const action = namedAction || segments[3] || '';
      if (action && !['open', 'close', 'toggle'].includes(action)) {
        issues.push(`[event] "${selector}" 的 UI_INTERACT 动作 "${action}" 不合法——动作只有 open | close | toggle（不存在 show / hide / display）`);
      }
    }

    const componentName = instances.get(somaId);
    if (componentName && !DOM_EVENTS.has(eventName)) {
      const entry = byName.get(componentName);
      const legalEmits = new Set((entry?.emits ?? []).map((emit) => emit.name));
      if (!legalEmits.has(eventName)) {
        issues.push(`[event] 实例 "${somaId}"（${componentName}）订阅了契约不存在的 emit "${eventName}"（可用：${[...legalEmits].join(', ') || '无'}）`);
      }
    } else if (componentName && DOM_EVENTS.has(eventName)) {
      const entry = byName.get(componentName);
      const legalEmits = new Set((entry?.emits ?? []).map((emit) => emit.name));
      if (legalEmits.has(eventName)) {
        continue; // change 这类与 DOM 同名的 emit 合法
      }
      issues.push(`[event] 组件实例 "${somaId}" 上不允许订阅 DOM 事件 "${eventName}"——组件交互入口只能是契约 emit`);
    } else if (!componentName && !DOM_EVENTS.has(eventName)) {
      // 普通锚点没有 emit 路由：名单外的小写名字 core 解析期按 emit 名放行（常见 DOM 名只打告警），
      // 页面编译照样通过；运行时引擎按事件名原样挂原生委托——mouseover 这类会冒泡的在锚点内
      // 子元素之间移动时反复触发，不冒泡的和拼错的永远不执行。与"组件实例上订阅 DOM 事件"
      // 同属订阅越出约定，同样报成问题让模型改写，不留到运行时。
      issues.push(
        `[event] 普通锚点 "${somaId}" 上不支持事件 "${eventName}"（可用：${[...DOM_EVENTS].join(', ')}）`
          + `——普通锚点不是组件实例，只能订阅这些 DOM 事件；替代写法：${unlistedAnchorEventAlternative(eventName, tooltipUsable)}`,
      );
    }
  }
}

/**
 * 取数声明的生成期核对。
 *
 * 与注册中心那道白名单是同一条规则的两个位置:这里**给修复机会**(问题回喂模型),
 * 那里**给硬保证**(落库前最后一道)。规则只写一遍——判据都是"路径必须在授权清单内"。
 *
 * 直接消费统一页面编译器产出的 dataConfig 而不是二次解析源文本；YAML 怎么写都不影响判定，
 * 数据段语法错误也已由同一次页面编译暴露。
 */
function checkDataBindings(
  config: ReturnType<typeof compilePageDeclaration>['dataConfig'],
  allowedApiPaths?: readonly string[],
): string[] {
  if (!config) return [];
  const paths = new Set<string>();
  for (const object of Object.values(config.objects ?? {})) {
    for (const source of object.from ?? []) {
      if (typeof source.api === 'string' && source.api.trim()) {
        paths.add(source.api.split('#')[0].split('?')[0].trim());
      }
    }
  }
  const declared = [...paths].sort();
  if (!allowedApiPaths) return [];
  const allowed = new Set(allowedApiPaths);
  const missing = declared.filter((path) => !allowed.has(path));
  if (missing.length === 0) return [];
  return [
    `[取数] 绑定了未授权的接口 ${missing.join('、')}——`
      + '只能逐字使用「可用数据接口」清单里给出的路径',
  ];
}