Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

32.8 KB
Raw Blame
/**
 * 主界面布局树(Layout Tree)—— 数据模型、校验与纯函数操作。
 *
 * 放在 shared 层的原因:renderer(渲染布局)与 main(持久化 layout.json 时校验/回退)
 * 必须使用同一套校验逻辑,避免两份实现漂移。本文件零依赖、零 IO、全部纯函数,
 * 任何操作都不原地修改输入(immutable),损坏输入永不抛异常(coerceLayout 兜底回默认)。
 *
 * 结构总览:
 *   Layout = sidebar(树外全高独立柱,会话列表) + content(递归分割树) + float(v1 恒空)
 * 核心规则:谁在分割树的外层,谁就不被里层切割;chat-main 恰好存在一个、不可关闭、不可折叠。
 */

/** 当前布局存档的 schema 版本;持久化迁移时按此判断。 */
export const LAYOUT_SCHEMA_VERSION = 1 as const;

/** 递归分割树的最大深度(含 pane 叶子层)。防止损坏/恶意存档造成递归渲染爆栈。 */
export const MAX_TREE_DEPTH = 8;

/** panelKind 字符串长度上限(防御性,存档里出现超长字符串按损坏处理)。 */
const MAX_PANEL_KIND_LENGTH = 128;

/**
 * 单个 split child 的份额下限:低于它的份额转移一律整单拒绝(不收窄),
 * 插入新面板时的初始份额也按它夹取。调用方(缝把手)应预先把 amount 夹到
 * 这条线以内 —— 拒绝会让拖动的整段位移作废,界面弹回原宽。
 */
export const MIN_SPLIT_CHILD_FRACTION = 0.05;

/**
 * 份额比较容差。夹取到下限的调用方算出的 amount 会带浮点残差
 * (`0.4589135021784424 - 0.05` 再减回去 = `0.04999999999999999`),
 * 裸比较 `< 0.05` 会把**恰好夹到边界**的合法转移判成非法 → 整单拒绝 → 松手回弹
 * (2026-07-29 Lizi 实测右栏拖到最大松手回弹的直接原因之一)。
 */
const FRACTION_TOLERANCE = 1e-9;

/**
 * 内置面板类型。`right-tabs` 同时是右侧页签组的 kind;其余页签组用
 * `tab-group:<边>`(见 tabGroupPanelKind),历史插件停靠面板曾用 `ghost:<id>`。
 */
export const BUILTIN_PANEL_KINDS = ['session-list', 'chat-main', 'right-tabs'] as const;
export type BuiltinPanelKind = (typeof BUILTIN_PANEL_KINDS)[number];

/**
 * 面板类型标识。
 *
 * 故意保持"开放命名空间"(任意非空字符串合法),而不是封闭枚举:
 * - 页签组按边注册为 `tab-group:<边>`,类型/校验/持久化零改动;
 * - 组里暂时没有页签、或存档里残留历史插件面板的 kind 时依然是**合法树**(渲染层
 *   查注册表查不到时隐藏该 pane 并回流空间)——绝不能因为"不认识"就把整棵树
 *   打回默认,否则关掉一组页签会毁掉用户全部布局;
 * - 同理,新版本新增的内置面板在旧版本上打开时也只是"隐藏",不是"重置"。
 *
 * `(string & {})` 是保留字面量自动补全的常用技巧,语义上等价于 string。
 */
export type PanelKind = BuiltinPanelKind | (string & {});

/** 叶子节点:一块面板的停靠位。 */
export type PaneNode = {
  type: 'pane';
  /** 布局内唯一 id(由调用方生成;纯函数层不产生随机值,保证可测可复现)。 */
  id: string;
  panelKind: PanelKind;
  /** 折叠态。注意:折叠是"贴边才有"的位置能力,本字段只存状态,能力判定在渲染层。 */
  collapsed?: boolean;
  /** 面板最小宽度(px)。chat-main 默认 400,见 createDefaultLayout。 */
  minWidth?: number;
};

/** 分割节点:往某个方向切一刀,children 的 fraction 为该方向上的占比。 */
export type SplitNode = {
  type: 'split';
  id: string;
  /** row = 水平排列(竖切),column = 垂直排列(横切)。 */
  direction: 'row' | 'column';
  children: { fraction: number; node: LayoutNode }[];
};

export type LayoutNode = PaneNode | SplitNode;

/** 浮层面板(WoW 式自由浮动)。v1 不启用,仅占位定型。 */
export type FloatPanel = {
  id: string;
  panelKind: PanelKind;
  x: number;
  y: number;
  width: number;
  height: number;
};

/** 全局唯一的一份布局(不随 session 变形;面板内容跟随会话,布局不跟随)。 */
export type Layout = {
  schemaVersion: typeof LAYOUT_SCHEMA_VERSION;
  /**
   * 会话列表:树外的全高独立柱,不被 content 的任何分割切到。
   * v1 只允许 edge: 'left';远期最多支持整柱镜像到最右,不可进入内容区。
   */
  sidebar: PaneNode & { edge: 'left' };
  /** 内容区 = 递归分割树。 */
  content: LayoutNode;
  /** v1 恒为空数组。 */
  float: FloatPanel[];
};

/** 校验结果。ok=false 时 reason 描述第一处违规(供日志,非用户文案)。 */
export type ValidateResult = { ok: true } | { ok: false; reason: string };

/** coerceLayout 的结果:fallback=true 表示输入不可用、已回退默认树。 */
export type CoerceResult = { layout: Layout; fallback: boolean; reason?: string };

/** 树操作的结果:applied=false 时 layout 即原输入(引用相等),reason 说明原因。 */
export type LayoutOpResult = { layout: Layout; applied: boolean; reason?: string };

// ---------------------------------------------------------------------------
// 默认布局
// ---------------------------------------------------------------------------

/**
 * 默认布局 = 今天的三栏样子:sidebar(会话列表)+ 内容区一刀竖切(聊天 0.5 / 工具 0.5)。
 * 0.5/0.5 对齐 useRightSidebarResize 的既有默认(DEFAULT_FRACTION = 0.5,右栏与聊天区
 * 1:1)——B1b 起宽度由树驱动,默认值必须与用户一直看到的 50/50 一致,不能引入视觉变化。
 * 每次调用返回全新深拷贝,调用方可安全修改。
 */
export function createDefaultLayout(): Layout {
  return {
    schemaVersion: LAYOUT_SCHEMA_VERSION,
    sidebar: { type: 'pane', id: 'sessions', panelKind: 'session-list', edge: 'left' },
    content: {
      type: 'split',
      id: 'root',
      direction: 'row',
      children: [
        {
          fraction: 0.5,
          node: { type: 'pane', id: 'chat', panelKind: 'chat-main', minWidth: 400 },
        },
        { fraction: 0.5, node: { type: 'pane', id: 'right', panelKind: 'right-tabs' } },
      ],
    },
    float: [],
  };
}

// ---------------------------------------------------------------------------
// 类型守卫与遍历
// ---------------------------------------------------------------------------

export function isPaneNode(node: LayoutNode): node is PaneNode {
  return node.type === 'pane';
}

export function isSplitNode(node: LayoutNode): node is SplitNode {
  return node.type === 'split';
}

function walkContentPanes(node: LayoutNode, out: PaneNode[]): void {
  if (node.type === 'pane') {
    out.push(node);
    return;
  }
  for (const child of node.children) walkContentPanes(child.node, out);
}

/** 按 sidebar → content(深度优先) → float 的顺序返回全部 pane(float 项转为 PaneNode 视图)。 */
export function walkPanes(layout: Layout): PaneNode[] {
  const out: PaneNode[] = [layout.sidebar];
  walkContentPanes(layout.content, out);
  for (const f of layout.float) out.push({ type: 'pane', id: f.id, panelKind: f.panelKind });
  return out;
}

/** 按 id 查找 pane(含 sidebar 与 float)。找不到返回 null。 */
export function findPaneById(layout: Layout, paneId: string): PaneNode | null {
  return walkPanes(layout).find((p) => p.id === paneId) ?? null;
}

/** 统计某 panelKind 在整份布局(含 sidebar 与 float)中的出现次数。 */
export function countPanelKind(layout: Layout, kind: PanelKind): number {
  return walkPanes(layout).filter((p) => p.panelKind === kind).length;
}

/** 某个 pane 在 content 分割树中的位置引用(用于按位置读写 fraction)。 */
export interface SplitChildRef {
  /** 所在分割节点的 id(setSplitChildFraction 的寻址键)。 */
  splitId: string;
  /** 在该分割 children 中的下标。 */
  childIndex: number;
  /** 该 child 当前的 fraction。 */
  fraction: number;
}

function findSplitChildByKindIn(node: LayoutNode, kind: PanelKind): SplitChildRef | null {
  if (node.type !== 'split') return null;
  for (let i = 0; i < node.children.length; i++) {
    const child = node.children[i];
    if (child.node.type === 'pane' && child.node.panelKind === kind) {
      return { splitId: node.id, childIndex: i, fraction: child.fraction };
    }
    const nested = findSplitChildByKindIn(child.node, kind);
    if (nested) return nested;
  }
  return null;
}

/**
 * 在 content 分割树中深度优先查找第一个 panelKind 匹配的 pane,返回其分割位置引用。
 * 找不到(该面板不在树里 / content 是单 pane)返回 null。
 * 消费方(如右栏宽度 hook)按 kind 寻址而非按方位寻址 —— 面板换到哪一侧都能找到。
 */
export function findSplitChildByPanelKind(layout: Layout, kind: PanelKind): SplitChildRef | null {
  return findSplitChildByKindIn(layout.content, kind);
}

// ---------------------------------------------------------------------------
// 校验
// ---------------------------------------------------------------------------

function isRecord(v: unknown): v is Record<string, unknown> {
  return typeof v === 'object' && v !== null && !Array.isArray(v);
}

function isValidId(v: unknown): v is string {
  return typeof v === 'string' && v.length > 0 && v.length <= 128;
}

function isValidPanelKind(v: unknown): v is string {
  return typeof v === 'string' && v.length > 0 && v.length <= MAX_PANEL_KIND_LENGTH;
}

/** 结构性校验单个节点(形状 + 深度 + fraction),把途经的 pane 与 id 收集起来供全局不变量检查。 */
function validateNodeShape(
  node: unknown,
  depth: number,
  ids: Set<string>,
  panes: PaneNode[],
): ValidateResult {
  if (depth > MAX_TREE_DEPTH) return { ok: false, reason: `tree deeper than ${MAX_TREE_DEPTH}` };
  if (!isRecord(node)) return { ok: false, reason: 'node is not an object' };

  if (!isValidId(node.id)) return { ok: false, reason: 'node id invalid' };
  if (ids.has(node.id)) return { ok: false, reason: `duplicate node id: ${node.id}` };
  ids.add(node.id);

  if (node.type === 'pane') {
    if (!isValidPanelKind(node.panelKind)) return { ok: false, reason: 'panelKind invalid' };
    if (node.collapsed !== undefined && typeof node.collapsed !== 'boolean') {
      return { ok: false, reason: 'collapsed must be boolean' };
    }
    if (
      node.minWidth !== undefined &&
      !(Number.isFinite(node.minWidth) && (node.minWidth as number) > 0)
    ) {
      return { ok: false, reason: 'minWidth must be a positive finite number' };
    }
    panes.push(node as unknown as PaneNode);
    return { ok: true };
  }

  if (node.type === 'split') {
    if (node.direction !== 'row' && node.direction !== 'column') {
      return { ok: false, reason: 'split direction invalid' };
    }
    if (!Array.isArray(node.children) || node.children.length < 2) {
      return { ok: false, reason: 'split needs at least 2 children' };
    }
    let fractionSum = 0;
    for (const child of node.children) {
      if (!isRecord(child)) return { ok: false, reason: 'split child is not an object' };
      if (!(Number.isFinite(child.fraction) && (child.fraction as number) > 0)) {
        return { ok: false, reason: 'child fraction must be a positive finite number' };
      }
      fractionSum += child.fraction as number;
      const r = validateNodeShape(child.node, depth + 1, ids, panes);
      if (!r.ok) return r;
    }
    if (Math.abs(fractionSum - 1) > 0.01) {
      return { ok: false, reason: `split fractions must sum to ~1, got ${fractionSum}` };
    }
    return { ok: true };
  }

  return { ok: false, reason: `unknown node type: ${String((node as { type?: unknown }).type)}` };
}

/**
 * 校验整份布局。只检查**结构性不变量**,不检查 panelKind 是否"已注册"——
 * kind 存不存在是面板注册表在渲染时的事(未安装的意识面板 = 隐藏,不 = 非法树)。
 *
 * 不变量清单(与设计文档 §6 对齐):
 *  1. schemaVersion 匹配;
 *  2. sidebar 必须是 session-list 且 edge='left';
 *  3. content 中 chat-main 恰好一个,且不允许出现 session-list(它只能在树外);
 *  4. chat-main 不可折叠(collapsed 不能为 true);
 *  5. split ≥2 children、fraction 为正有限数、深度 ≤ MAX_TREE_DEPTH、id 全局唯一;
 *  6. v1 float 必须为空。
 */
export function validateLayout(input: Layout): ValidateResult {
  if (!isRecord(input)) return { ok: false, reason: 'layout is not an object' };
  if (input.schemaVersion !== LAYOUT_SCHEMA_VERSION) {
    return { ok: false, reason: `schemaVersion must be ${LAYOUT_SCHEMA_VERSION}` };
  }
  if (!Array.isArray(input.float) || input.float.length !== 0) {
    return { ok: false, reason: 'float must be an empty array in v1' };
  }

  const sidebar = input.sidebar as unknown;
  if (!isRecord(sidebar) || sidebar.type !== 'pane')
    return { ok: false, reason: 'sidebar must be a pane' };
  if (sidebar.panelKind !== 'session-list')
    return { ok: false, reason: 'sidebar must be session-list' };
  if (sidebar.edge !== 'left') return { ok: false, reason: "sidebar edge must be 'left' in v1" };
  if (!isValidId(sidebar.id)) return { ok: false, reason: 'sidebar id invalid' };

  const ids = new Set<string>([sidebar.id as string]);
  const contentPanes: PaneNode[] = [];
  const shape = validateNodeShape(input.content, 1, ids, contentPanes);
  if (!shape.ok) return shape;

  const chatMains = contentPanes.filter((p) => p.panelKind === 'chat-main');
  if (chatMains.length !== 1) {
    return {
      ok: false,
      reason: `content must contain exactly one chat-main (got ${chatMains.length})`,
    };
  }
  if (chatMains[0].collapsed === true)
    return { ok: false, reason: 'chat-main must not be collapsed' };
  if (contentPanes.some((p) => p.panelKind === 'session-list')) {
    return { ok: false, reason: 'session-list must stay outside the content tree' };
  }
  return { ok: true };
}

/**
 * 把来源不可信的数据(持久化文件、IPC 入参)转成一份**必然合法**的布局。
 * 任何解析/校验失败都静默回退默认树,只带回 reason 供调用方打日志——永不抛异常。
 * 这是"存档改坏 → 重启自动复原"行为的实现基础。
 */
export function coerceLayout(raw: unknown): CoerceResult {
  if (!isRecord(raw)) {
    return { layout: createDefaultLayout(), fallback: true, reason: 'not an object' };
  }
  let cloned: Layout;
  try {
    // 深拷贝隔离外部引用;不可序列化的输入(函数、Symbol 等)会在此抛出并走回退。
    // structuredClone 本身支持循环引用,不会为此抛错;循环引用的回退由后续 validateLayout 完成。
    cloned = structuredClone(raw) as Layout;
  } catch {
    return { layout: createDefaultLayout(), fallback: true, reason: 'not cloneable' };
  }
  const v = validateLayout(cloned);
  if (!v.ok) return { layout: createDefaultLayout(), fallback: true, reason: v.reason };
  return { layout: cloned, fallback: false };
}

// ---------------------------------------------------------------------------
// 操作(immutable:全部返回新树;非法操作返回原引用 + applied:false)
// ---------------------------------------------------------------------------

/** 深拷贝 + 出口校验的公共收尾:任何操作都不可能产出非法树。 */
function finishOp(original: Layout, mutated: Layout, reason: string): LayoutOpResult {
  const v = validateLayout(mutated);
  if (!v.ok) return { layout: original, applied: false, reason: `${reason}: ${v.reason}` };
  return { layout: mutated, applied: true };
}

/**
 * 设置某个 pane 的折叠态。chat-main 不可折叠(由出口校验兜底拒绝)。
 * 注意:能否折叠(是否贴边)是渲染层的位置判定,本函数只负责状态写入的合法性。
 */
export function setPaneCollapsed(
  layout: Layout,
  paneId: string,
  collapsed: boolean,
): LayoutOpResult {
  if (!findPaneById(layout, paneId)) {
    return { layout, applied: false, reason: `pane not found: ${paneId}` };
  }
  const next = structuredClone(layout);
  for (const pane of walkPanes(next)) {
    if (pane.id === paneId) pane.collapsed = collapsed;
  }
  // sidebar 是独立字段,walkPanes 返回的正是其引用,已被上面覆盖;float 视图项不回写(v1 恒空)。
  return finishOp(layout, next, 'setPaneCollapsed rejected');
}

/**
 * 设置分割节点中某个 child 的 fraction,并对该分割的全部 children 归一化(总和=1)。
 * fraction 语义与现右栏一致:占比制,窗口缩放时两侧按比例变化。
 */
export function setSplitChildFraction(
  layout: Layout,
  splitId: string,
  childIndex: number,
  fraction: number,
): LayoutOpResult {
  if (!(Number.isFinite(fraction) && fraction > 0 && fraction < 1)) {
    return { layout, applied: false, reason: 'fraction must be between 0 and 1 (exclusive)' };
  }
  if (!Number.isInteger(childIndex)) {
    return { layout, applied: false, reason: `child index must be an integer: ${childIndex}` };
  }
  const next = structuredClone(layout);
  const split = findSplitById(next.content, splitId);
  if (!split) return { layout, applied: false, reason: `split not found: ${splitId}` };
  if (childIndex < 0 || childIndex >= split.children.length) {
    return { layout, applied: false, reason: `child index out of range: ${childIndex}` };
  }
  // Assign the exact requested fraction and redistribute the remainder among siblings
  const siblings = split.children;
  const siblingSum = siblings.reduce((acc, c, i) => acc + (i === childIndex ? 0 : c.fraction), 0);
  siblings[childIndex].fraction = fraction;
  const remainder = 1 - fraction;
  for (let i = 0; i < siblings.length; i++) {
    if (i === childIndex) continue;
    siblings[i].fraction =
      siblingSum > 0
        ? (siblings[i].fraction / siblingSum) * remainder
        : remainder / (siblings.length - 1);
  }
  normalizeSplitFractions(split);
  return finishOp(layout, next, 'setSplitChildFraction rejected');
}

/**
 * 往 content 根分割插入一个新 pane —— "加装面板"的底层操作。
 * - content 必须是分割(默认树满足;单 pane content 暂不支持);
 * - 新 child 分走 fraction 份额(夹取到 [0.05, 0.8]),已有 children 等比让出,总和保持 1;
 * - index 越界自动夹取(默认追加到最右);
 * - id 重复 / 其它不变量破坏由出口校验兜底拒绝(返回原树,不半途落地)。
 */
export function insertRootSplitPane(
  layout: Layout,
  pane: { id: string; panelKind: PanelKind; minWidth?: number },
  opts: { index?: number; fraction?: number } = {},
): LayoutOpResult {
  if (layout.content.type !== 'split') {
    return { layout, applied: false, reason: 'content is not a split' };
  }
  const fraction = Math.min(0.8, Math.max(MIN_SPLIT_CHILD_FRACTION, opts.fraction ?? 0.2));
  const next = structuredClone(layout);
  const split = next.content as SplitNode;
  const index = Math.min(split.children.length, Math.max(0, opts.index ?? split.children.length));
  for (const child of split.children) child.fraction *= 1 - fraction;
  const node: PaneNode = { type: 'pane', id: pane.id, panelKind: pane.panelKind };
  if (pane.minWidth !== undefined) node.minWidth = pane.minWidth;
  split.children.splice(index, 0, { fraction, node });
  normalizeSplitFractions(split);
  return finishOp(layout, next, 'insertRootSplitPane rejected');
}

/**
 * 从 content 根分割移除第一个匹配 panelKind 的 pane —— "卸载面板"的底层操作。
 * 剩余 children 份额归一。拒绝:目标不存在 / 移除后 children < 2(根分割至少
 * 两块;收缩成单 pane 暂不支持)/ 移除 chat-main(出口校验兜底)。
 */
export function removeRootSplitPaneByKind(layout: Layout, kind: PanelKind): LayoutOpResult {
  if (layout.content.type !== 'split') {
    return { layout, applied: false, reason: 'content is not a split' };
  }
  const idx = layout.content.children.findIndex(
    (c) => c.node.type === 'pane' && c.node.panelKind === kind,
  );
  if (idx < 0) return { layout, applied: false, reason: `pane kind not found: ${kind}` };
  if (layout.content.children.length <= 2) {
    return { layout, applied: false, reason: 'root split needs at least 2 children' };
  }
  const next = structuredClone(layout);
  const split = next.content as SplitNode;
  split.children.splice(idx, 1);
  normalizeSplitFractions(split);
  return finishOp(layout, next, 'removeRootSplitPaneByKind rejected');
}

/**
 * 交换 content 根分割中两个 panelKind 所在 child 的位置(N 面板拖拽换位的
 * 提交操作)。kind 可以是根 pane,也可以位于根级插件 column 内;后者交换整列,
 * 避免把内置面板塞进 ghost-only column。child 整体交换,fraction 随区域走。
 */
export function swapRootSplitChildrenByKind(
  layout: Layout,
  kindA: PanelKind,
  kindB: PanelKind,
): LayoutOpResult {
  if (layout.content.type !== 'split') {
    return { layout, applied: false, reason: 'content is not a split' };
  }
  const a = rootChildIndexContainingKind(layout, kindA);
  const b = rootChildIndexContainingKind(layout, kindB);
  if (a < 0 || b < 0)
    return { layout, applied: false, reason: `pane kind not found: ${a < 0 ? kindA : kindB}` };
  if (a === b) return { layout, applied: false, reason: 'cannot swap within the same root child' };
  const next = structuredClone(layout);
  const split = next.content as SplitNode;
  [split.children[a], split.children[b]] = [split.children[b], split.children[a]];
  return finishOp(layout, next, 'swapRootSplitChildrenByKind rejected');
}

// ---------------------------------------------------------------------------
// 页签组(tab group)—— 承载右侧栏页签的 pane,可停在聊天区四条边
// ---------------------------------------------------------------------------

/**
 * 页签组标识 = 它相对聊天区所在的边。右侧组是历史上的右侧栏(panelKind 沿用
 * `right-tabs`,老存档零迁移);其余三组按需插入树里,pane 一旦存在就保留
 * (组里没有页签时由渲染层按「未注册 kind」隐藏,位置与宽度记忆不丢)。
 */
export const TAB_GROUP_IDS = ['left', 'right', 'top', 'bottom'] as const;
export type TabGroupId = (typeof TAB_GROUP_IDS)[number];

/** 承载聊天区与上下页签组的纵向分割节点 id(上下组只在这一层 column 里)。 */
export const CHAT_COLUMN_SPLIT_ID = 'chat-column';

const TAB_GROUP_KIND_PREFIX = 'tab-group:';

export function isTabGroupId(value: unknown): value is TabGroupId {
  return typeof value === 'string' && (TAB_GROUP_IDS as readonly string[]).includes(value);
}

/**
 * 某个 pane 相对聊天区(chat-main)在哪一边:取两者最近公共分割的方向与先后。
 * 用于把升级前停靠在布局树里的插件面板(`ghost:<id>`)迁成对应边的页签组。
 * 找不到 pane / chat-main,或两者不在同一棵分割树里,返回 null。
 */
export function paneEdgeRelativeToChat(layout: Layout, kind: PanelKind): TabGroupId | null {
  const pathTo = (
    node: LayoutNode,
    target: PanelKind,
  ): { split: SplitNode; index: number }[] | null => {
    if (node.type === 'pane') return node.panelKind === target ? [] : null;
    for (let i = 0; i < node.children.length; i++) {
      const rest = pathTo(node.children[i].node, target);
      if (rest) return [{ split: node, index: i }, ...rest];
    }
    return null;
  };
  const toPane = pathTo(layout.content, kind);
  const toChat = pathTo(layout.content, 'chat-main');
  if (!toPane || !toChat) return null;
  for (let depth = 0; depth < Math.min(toPane.length, toChat.length); depth++) {
    const a = toPane[depth];
    const b = toChat[depth];
    if (a.index === b.index) continue;
    const before = a.index < b.index;
    if (a.split.direction === 'row') return before ? 'left' : 'right';
    return before ? 'top' : 'bottom';
  }
  return null;
}

/** 页签组对应的 panelKind:右侧组 = `right-tabs`,其余 = `tab-group:<id>`。 */
export function tabGroupPanelKind(groupId: TabGroupId): PanelKind {
  return groupId === 'right' ? 'right-tabs' : `${TAB_GROUP_KIND_PREFIX}${groupId}`;
}

/** panelKind → 页签组 id;不是页签组的 pane 返回 null。 */
export function tabGroupIdFromPanelKind(kind: PanelKind): TabGroupId | null {
  if (kind === 'right-tabs') return 'right';
  if (!kind.startsWith(TAB_GROUP_KIND_PREFIX)) return null;
  const id = kind.slice(TAB_GROUP_KIND_PREFIX.length);
  return isTabGroupId(id) && id !== 'right' ? id : null;
}

function rootChildIndexContainingKind(layout: Layout, kind: PanelKind): number {
  if (layout.content.type !== 'split' || layout.content.direction !== 'row') return -1;
  const contains = (node: LayoutNode): boolean => {
    if (node.type === 'pane') return node.panelKind === kind;
    return node.children.some((child) => contains(child.node));
  };
  return layout.content.children.findIndex((child) => contains(child.node));
}

/** 左右组插入时的初始宽度份额;上下组插入时在聊天列里的初始高度份额。 */
const TAB_GROUP_SIDE_FRACTION = 0.25;
const TAB_GROUP_STACK_FRACTION = 0.35;

/**
 * 保证某个页签组的 pane 在树里(用户第一次把页签移到该边时调用):
 * - left / right:插到根横排里聊天区(或包着聊天区的列)的前 / 后,与其它根 child
 *   等比让出份额;
 * - top / bottom:聊天区 pane 原地换成一层 `chat-column` 纵向分割,组在聊天区的
 *   上 / 下;列已存在则插到列首 / 列尾。
 * 已在树里 → applied:false(原树)。不负责删除:组空了由渲染层隐藏,位置记忆保留。
 */
export function ensureTabGroupPane(layout: Layout, groupId: TabGroupId): LayoutOpResult {
  const kind = tabGroupPanelKind(groupId);
  if (findSplitChildByPanelKind(layout, kind)) {
    return { layout, applied: false, reason: `tab group already present: ${groupId}` };
  }
  if (layout.content.type !== 'split' || layout.content.direction !== 'row') {
    return { layout, applied: false, reason: 'content root must be a row split' };
  }
  const chatRootIndex = rootChildIndexContainingKind(layout, 'chat-main');
  if (chatRootIndex < 0) return { layout, applied: false, reason: 'chat-main not found' };
  const paneId = `tab-group-${groupId}`;

  if (groupId === 'left' || groupId === 'right') {
    return insertRootSplitPane(
      layout,
      { id: paneId, panelKind: kind },
      {
        index: groupId === 'left' ? chatRootIndex : chatRootIndex + 1,
        fraction: TAB_GROUP_SIDE_FRACTION,
      },
    );
  }

  const next = structuredClone(layout);
  const root = next.content as SplitNode;
  const rootChild = root.children[chatRootIndex];
  const pane: PaneNode = { type: 'pane', id: paneId, panelKind: kind };
  if (rootChild.node.type === 'pane') {
    const chat = rootChild.node;
    rootChild.node = {
      type: 'split',
      id: CHAT_COLUMN_SPLIT_ID,
      direction: 'column',
      children:
        groupId === 'top'
          ? [
              { fraction: TAB_GROUP_STACK_FRACTION, node: pane },
              { fraction: 1 - TAB_GROUP_STACK_FRACTION, node: chat },
            ]
          : [
              { fraction: 1 - TAB_GROUP_STACK_FRACTION, node: chat },
              { fraction: TAB_GROUP_STACK_FRACTION, node: pane },
            ],
    };
    return finishOp(layout, next, 'ensureTabGroupPane rejected');
  }
  const column = rootChild.node;
  if (column.direction !== 'column') {
    return { layout, applied: false, reason: 'chat container must be a column split' };
  }
  for (const child of column.children) child.fraction *= 1 - TAB_GROUP_STACK_FRACTION;
  column.children.splice(groupId === 'top' ? 0 : column.children.length, 0, {
    fraction: TAB_GROUP_STACK_FRACTION,
    node: pane,
  });
  normalizeSplitFractions(column);
  return finishOp(layout, next, 'ensureTabGroupPane rejected');
}

/**
 * 在分割内把 amount 份额从 fromIndex child 转移给 toIndex child(引擎分割线
 * 拖宽的提交操作 —— 只动缝两侧的邻居,其余 children 份额不受影响;与
 * setSplitChildFraction 的"全体按比例重分"语义不同)。
 * 双方转移后都必须仍 ≥ MIN_SPLIT_CHILD_FRACTION,否则拒绝(调用方应预先按像素
 * 下限夹取 amount);恰好夹到边界的转移**必须放行**,判定带浮点容差。
 */
export function transferSplitFraction(
  layout: Layout,
  splitId: string,
  fromIndex: number,
  toIndex: number,
  amount: number,
): LayoutOpResult {
  if (!(Number.isFinite(amount) && amount !== 0)) {
    return { layout, applied: false, reason: 'amount must be a non-zero finite number' };
  }
  if (!Number.isInteger(fromIndex) || !Number.isInteger(toIndex) || fromIndex === toIndex) {
    return { layout, applied: false, reason: 'invalid child indices' };
  }
  const next = structuredClone(layout);
  const split = findSplitById(next.content, splitId);
  if (!split) return { layout, applied: false, reason: `split not found: ${splitId}` };
  if (
    fromIndex < 0 ||
    fromIndex >= split.children.length ||
    toIndex < 0 ||
    toIndex >= split.children.length
  ) {
    return { layout, applied: false, reason: 'child index out of range' };
  }
  const from = split.children[fromIndex];
  const to = split.children[toIndex];
  // 容差:夹到下限的合法转移不能被浮点残差判死(见 FRACTION_TOLERANCE)。
  const floor = MIN_SPLIT_CHILD_FRACTION - FRACTION_TOLERANCE;
  if (from.fraction - amount < floor || to.fraction + amount < floor) {
    return {
      layout,
      applied: false,
      reason: `transfer would shrink a child below ${MIN_SPLIT_CHILD_FRACTION}`,
    };
  }
  from.fraction -= amount;
  to.fraction += amount;
  normalizeSplitFractions(split);
  return finishOp(layout, next, 'transferSplitFraction rejected');
}

/**
 * 多来源接力的份额转移:amount 全额从 sources(按下标顺序)转移到 toIndex,每个
 * 来源各自保住 MIN_SPLIT_CHILD_FRACTION 下限 —— 前一个扣到下限后,剩余差额由
 * 后面的继续接;接力走完仍有缺口则整单拒绝(返回原树)。
 *
 * 为什么需要(2026-08-17 实测):压缩 chat 的拖缝松手要把**像素口径**的增量写回
 * 账本,但 chat 的画面宽(flex 吸收折叠邻居让出的空间)可以远大于自己的树份额,
 * 两方转移会被 0.05 账本地板整单拒绝 —— chat 树份额被拖到 0.05 后那条缝彻底
 * 冻住,压不到 400px 产品下限。差额改由"渲染宽为 0 却占着账"的折叠兄弟接力出账
 * (画面上那块本就被弹性 chat 吸收),账本与画面重新对齐。调用方(LayoutRoot)
 * 按"实测宽为 0"挑来源;本函数只管写树合法,不理解折叠语义。
 */
export function transferSplitFractionRelay(
  layout: Layout,
  splitId: string,
  sources: number[],
  toIndex: number,
  amount: number,
): LayoutOpResult {
  if (!(Number.isFinite(amount) && amount > 0)) {
    return { layout, applied: false, reason: 'amount must be a positive finite number' };
  }
  if (!Array.isArray(sources) || sources.length === 0) {
    return { layout, applied: false, reason: 'sources must be a non-empty array' };
  }
  if (!Number.isInteger(toIndex)) {
    return { layout, applied: false, reason: `toIndex must be an integer: ${toIndex}` };
  }
  const seen = new Set<number>();
  for (const index of sources) {
    if (!Number.isInteger(index)) {
      return { layout, applied: false, reason: `source index must be an integer: ${index}` };
    }
    if (index === toIndex) {
      return { layout, applied: false, reason: 'toIndex must not appear in sources' };
    }
    if (seen.has(index)) {
      return { layout, applied: false, reason: `duplicate source index: ${index}` };
    }
    seen.add(index);
  }
  const next = structuredClone(layout);
  const split = findSplitById(next.content, splitId);
  if (!split) return { layout, applied: false, reason: `split not found: ${splitId}` };
  const bounds = split.children.length;
  if (toIndex < 0 || toIndex >= bounds || sources.some((index) => index < 0 || index >= bounds)) {
    return { layout, applied: false, reason: 'child index out of range' };
  }
  // 容差与两方转移同款:夹到下限的合法接力不能被浮点残差判死。
  const floor = MIN_SPLIT_CHILD_FRACTION - FRACTION_TOLERANCE;
  let remaining = amount;
  for (const index of sources) {
    if (remaining <= FRACTION_TOLERANCE) break;
    const child = split.children[index];
    const take = Math.min(remaining, child.fraction - floor);
    if (take <= 0) continue;
    child.fraction -= take;
    remaining -= take;
  }
  if (remaining > FRACTION_TOLERANCE) {
    return {
      layout,
      applied: false,
      reason: `sources cannot cover the transfer, short by ${remaining}`,
    };
  }
  split.children[toIndex].fraction += amount - remaining;
  normalizeSplitFractions(split);
  return finishOp(layout, next, 'transferSplitFractionRelay rejected');
}

function findSplitById(node: LayoutNode, splitId: string): SplitNode | null {
  if (node.type !== 'split') return null;
  if (node.id === splitId) return node;
  for (const child of node.children) {
    const found = findSplitById(child.node, splitId);
    if (found) return found;
  }
  return null;
}

/** 将一个分割节点 children 的 fraction 原地归一化为总和 1(仅内部使用,外部入口皆 immutable)。 */
function normalizeSplitFractions(split: SplitNode): void {
  const sum = split.children.reduce((acc, c) => acc + c.fraction, 0);
  if (!(Number.isFinite(sum) && sum > 0)) return;
  for (const child of split.children) child.fraction = child.fraction / sum;
}