@loomhelm/multi-task-flow 0.0.0-stage → 0.2.1

package/toolkit/skills/multi-task-flow/web/details-content.ts

@@ -0,0 +1,296 @@
+import { hasArchiveAction, archivePresentation, renderArchiveAction, type ArchiveAction } from "./conversation-control";
+import { initialOutput, paintOutput } from "./agent-output";
+import { createProfileEditor, type ProfileEditorContext } from "./profile-editor";
+import { conversationUrl } from "./links";
+import { formatDuration } from "./time";
+import { renderTimestamp } from "./timestamp";
+import { renderStatusRow } from "./status-row";
+import { renderGroupPreview, renderTaskPreview } from "./preview-content";
+import { attachDependencyTooltip, renderDependencyTooltip, type DependencyTooltipItem } from "./dependency-tooltip";
+import type { Group, Task, View } from "./model";
+import { dependencyLabel, groupExecutionVisualState, stateLabel, taskKindLabel } from "./labels";
+import { buildGraphProjection, nodeTitle, type GraphBoundaryDependency, type GraphDependencyPath, type GraphProjectionEdge } from "./graph-projection";
+
+type DetailContentContext = {
+  getData: () => View | null;
+  labels: Record<string, string>;
+  labelTask: (task: Task) => string;
+  time: (value: string | null) => string;
+  safeExternal: (url: string | null) => string | null;
+  profileContext?: () => ProfileEditorContext;
+  archiveConversation?: ArchiveAction;
+};
+
+function text(tag: string, value: string, ...classNames: string[]): HTMLElement {
+  const node = document.createElement(tag);
+  node.className = classNames.join(" ");
+  node.textContent = value;
+  return node;
+}
+
+function clearDetails(): HTMLElement {
+  const container = document.getElementById("details-content")!;
+  document.getElementById("details-summary")?.replaceChildren();
+  delete container.dataset.selection;
+  container.replaceChildren();
+  container.scrollTop = 0;
+  container.className = "details-empty";
+  const rule = text("span", "", "empty-rule");
+  rule.setAttribute("aria-hidden", "true");
+  container.append(rule, text("strong", "选择交付单元或任务"), text("span", "查看依赖、运行时间和原生会话链接"));
+  return container;
+}
+
+function field(container: HTMLElement, name: string, value: HTMLElement | string): void {
+  const row = text("div", "", "detail-field");
+  row.append(text("div", name, "detail-label"));
+  const content = text("div", "", "detail-value");
+  content.append(typeof value === "string" ? document.createTextNode(value) : value);
+  row.append(content);
+  container.append(row);
+}
+
+function emptyOutput(): HTMLElement {
+  const value = text("span", "", "detail-empty-output");
+  value.dataset.emptyLabel = "尚无 Agent 输出";
+  value.setAttribute("aria-label", "尚无 Agent 输出");
+  return value;
+}
+
+function link(label: string, url: string | null): HTMLElement {
+  if (url === null) return text("span", "示例对话（Mock）");
+  const anchor = document.createElement("a");
+  anchor.textContent = label;
+  anchor.href = url;
+  if (url.startsWith("https://")) anchor.rel = "noopener noreferrer";
+  return anchor;
+}
+
+function durationValue(start: string | null, end: string | null): HTMLElement {
+  const value = text("strong", formatDuration(start, end), "detail-duration");
+  value.dataset.durationStart = start ?? "";
+  value.dataset.durationEnd = end ?? "";
+  return value;
+}
+
+function coordinatorValue(group: Group): string {
+  const status = group.coordinator?.status ?? (group.delivery_unit_kind === "bootstrap"
+    ? group.agent_thread_id ? "bound" : "unknown"
+    : group.agent_thread_id ? "bound" : "not_created");
+  if (status === "bound") return group.delivery_unit_kind === "bootstrap" ? "主对话已绑定" : "已绑定";
+  return status === "not_created" ? "尚未创建" : "未知";
+}
+
+function readinessValue(group: Group): string {
+  const readiness = group.runtime_readiness;
+  if (!readiness) return "未知";
+  const status = readiness.status === "ready" ? "Ready" : readiness.status === "blocked" ? "Blocked" : "Unknown";
+  const blockers = readiness.blockers.map((blocker) => {
+    const resource = blocker.resource
+      ? ` · 资源：${blocker.resource.status === "not_created" ? "尚未创建" : "未知"}`
+      : "";
+    return `${blocker.message}${resource}`;
+  });
+  return [status, ...blockers].join(" · ");
+}
+
+function atomList(atoms: Task["atoms"] | Group["atoms"], dependencies: (index: number) => DependencyTooltipItem[], focusedAtomId?: string | null, parent?: { kind: "task" | "group"; id: string }): HTMLElement | string {
+  if (!atoms?.length) return "未配置原子任务";
+  const list = document.createElement("ol");
+  list.className = "atom-list";
+  const wrapper = document.createElement("div");
+  wrapper.append(list);
+  const current = atoms.find((atom) => atom.status === "running" || atom.status === "blocked") ?? atoms.find((atom) => atom.status === "planned");
+  for (const [index, atom] of atoms.entries()) {
+    const item = document.createElement("li");
+    item.dataset.status = atom.status;
+    if (parent) { item.dataset.contextKind = "atom"; item.dataset.contextId = atom.id; item.dataset.contextParentKind = parent.kind; item.dataset.contextParentId = parent.id; }
+    item.tabIndex = 0;
+    if (atom.id === current?.id) item.dataset.current = "true";
+    if (atom.id === focusedAtomId) { item.dataset.focused = "true"; item.setAttribute("aria-current", "true"); }
+    item.append(renderStatusRow({ name: atom.title, status: atom.status, completedAt: atom.completed_at }));
+    list.append(item);
+    wrapper.append(attachDependencyTooltip(item, dependencies(index), `${atom.title}，查看依赖`));
+  }
+  return wrapper;
+}
+
+function pathValue(path: GraphDependencyPath, index: number | null): string {
+  const conditions = path.requires.length ? path.requires.map(dependencyLabel).join(" → ") : "未声明条件";
+  const rawEdges = path.sourceEdgeIds.length ? path.sourceEdgeIds.join("、") : "无";
+  const boundary = path.boundaryNodeIds.length ? `；隐藏边界：${path.boundaryNodeIds.join("、")}` : "";
+  const truncated = path.truncated ? "；其余路径已省略" : "";
+  return `${index === null ? "" : `路径${index}：`}条件：${conditions}；原始边：${rawEdges}${boundary}${truncated}`;
+}
+
+function dependencyValue(projection: ReturnType<typeof buildGraphProjection>, edge: GraphProjectionEdge, neighborId: string, data: View): DependencyTooltipItem {
+  const paths = edge.paths.map((path, index) => pathValue(path, edge.paths.length > 1 ? index + 1 : null)).join("；");
+  const node = projection.nodes.find((item) => item.id === neighborId);
+  const task = node?.nodeKind === "task" ? data.tasks.find((item) => item.id === node.refId) : null;
+  const completedAt = task?.finished_at ?? data.actual_milestones.find((item) => item.node_id === node?.sourceNodeId)?.occurred_at;
+  return { name: nodeTitle(projection, neighborId), state: paths, status: task?.state ?? (completedAt ? "completed" : node?.state ?? "planned"), completedAt };
+}
+
+function boundaryValue(boundary: GraphBoundaryDependency): DependencyTooltipItem {
+  const name = boundary.direction === "incoming" ? "计划入口" : "计划出口";
+  const paths = boundary.paths.map((path, index) => pathValue(path, boundary.paths.length > 1 ? index + 1 : null)).join("；");
+  return { name, state: paths };
+}
+
+function dependenciesFor(projection: ReturnType<typeof buildGraphProjection>, nodeId: string | undefined, direction: "incoming" | "outgoing", data: View): DependencyTooltipItem[] {
+  if (!nodeId) return [];
+  const edges = projection.edges.filter((edge) => direction === "incoming" ? edge.target === nodeId : edge.source === nodeId);
+  const boundaries = projection.boundaryDependencies.filter((item) => item.direction === direction && item.nodeId === nodeId);
+  const values = [
+    ...edges.map((edge) => dependencyValue(projection, edge, direction === "incoming" ? edge.source : edge.target, data)),
+    ...boundaries.map(boundaryValue),
+  ];
+  return values;
+}
+
+export function createDetailContent(context: DetailContentContext) {
+  function begin(kind: "task" | "group", id: string, title: string, state: string) {
+    const container = document.getElementById("details-content")!;
+    const selection = `${kind}:${id}`;
+    const top = container.dataset.selection === selection ? container.scrollTop : 0;
+    container.dataset.selection = selection;
+    container.replaceChildren();
+    container.className = "";
+    const summary = document.getElementById("details-summary")!;
+    summary.replaceChildren(text("div", title, "detail-title"), text("div", state, "detail-state"));
+    return { container, restore: () => { container.scrollTop = top; } };
+  }
+  const showTask = (task: Task): void => {
+    const data = context.getData();
+    if (!data) return;
+    const { container, restore } = begin("task", task.id, task.title, context.labelTask(task));
+    const currentGroup = data.groups.find((group) => group.id === task.group_id)?.title ?? task.group_id;
+    const executionGroups = [...new Set(data.actual_intervals.filter((row) => row.task_id === task.id).map((row) => row.group_id))].map((id) => data.groups.find((group) => group.id === id)?.title ?? id);
+    field(container, "所属交付单元", currentGroup);
+    if (executionGroups.length > 1) field(container, "执行交付单元历史", executionGroups.join("、"));
+    field(container, "类型", taskKindLabel(task.kind));
+    if (context.profileContext) {
+      const profileContext = context.profileContext();
+      field(container, "执行配置", createProfileEditor(profileContext, "task", task.id, task.execution_profile ?? null, task.effective_execution_profile ?? data.orchestration.execution_profile ?? null, data.profile_read_only ? "当前视图只读或尚未迁移" : task.profile_freeze_reason ?? (task.thread_id ? "对话已创建" : null), task.execution_profile_source === "recommendation" ? `按任务类型 ${task.kind} 推荐 · ${task.execution_profile_rule ?? "kind-v1"}` : null));
+    }
+    if (task.disposition && task.disposition !== "active") field(container, "任务处置", task.disposition);
+    if (task.is_held && task.hold_reason) field(container, "计划修订暂停", task.hold_reason);
+    const node = data.nodes.find((item) => item.kind === "task" && item.ref_id === task.id);
+    const projection = buildGraphProjection(data);
+    const predecessors = dependenciesFor(projection, node?.id, "incoming", data);
+    const successors = dependenciesFor(projection, node?.id, "outgoing", data);
+    const taskAtoms = task.atoms ?? task.planned_atoms;
+    field(container, "原子任务", atomList(taskAtoms, (index) => {
+      const id = taskAtoms![index]!.id;
+      return (data.atomic_edges ?? []).filter((edge) => edge.to_atom_id === id).map((edge) => {
+        const source = data.tasks.flatMap((item) => item.atoms ?? item.planned_atoms ?? []).find((atom) => atom.id === edge.from_atom_id);
+        return { name: source?.title ?? edge.from_atom_id, state: "", status: source?.status ?? "unknown", completedAt: source?.completed_at };
+      });
+    }, null, { kind: "task", id: task.id }));
+    field(container, "前驱", renderDependencyTooltip(predecessors, predecessors.length ? `查看 ${predecessors.length} 项依赖` : "无依赖"));
+    field(container, "后继", renderDependencyTooltip(successors, successors.length ? `查看 ${successors.length} 项依赖` : "无依赖"));
+    const projectedNode = projection.nodes.find((item) => item.sourceNodeId === node?.id);
+    const plannedGroup = projectedNode?.plannedGroupId && projectedNode.plannedGroupId !== task.group_id ? data.groups.find((group) => group.id === projectedNode.plannedGroupId)?.title ?? projectedNode.plannedGroupId : null;
+    if (plannedGroup) field(container, "计划归属交付单元", plannedGroup);
+    if (task.blocker) field(container, "等待原因", task.blocker);
+    field(container, "开始时间", renderTimestamp(task.started_at));
+    field(container, "完成时间", renderTimestamp(task.finished_at));
+    field(container, "持续时间", durationValue(task.started_at, task.finished_at));
+    const output = text("div", "", "detail-agent-output");
+    output.dataset.outputTaskId = task.id; output.dataset.outputFull = "true";
+    paintOutput(output, task.latest_agent_output ?? initialOutput(task.thread_id), true);
+    field(container, "最新 Agent 输出", output);
+    if (task.state === "agent_idle") field(container, "运行时提示", "Agent 当前没有活跃 turn，可能需要人工恢复");
+    if (task.state === "agent_idle") {
+      const observed = task.latest_agent_output;
+      if (observed?.observed_at) field(container, "运行时观察时间", renderTimestamp(observed.observed_at));
+      if (observed?.runtime_turn_id) field(container, "观察 Turn", observed.runtime_turn_id);
+    }
+    const conversation = text("div", "", "detail-conversation");
+    const conversationActions = text("div", "", "detail-conversation-actions");
+    conversationActions.append(task.thread_id ? link("打开对话", conversationUrl(task.thread_id)) : text("span", "尚未创建"));
+    if (hasArchiveAction(task)) conversationActions.append(renderArchiveAction(task, context.archiveConversation, data.profile_read_only === true));
+    conversation.append(conversationActions);
+    const archive = task.conversation_resource;
+    if (archive?.error || archive?.status.endsWith("failed") || archive?.status.endsWith("unknown")) {
+      const presentation = archivePresentation(task);
+      conversation.append(text("p", `${presentation.label}：${presentation.description}`, "detail-conversation-notice"));
+    }
+    field(container, "任务对话", conversation);
+    field(container, "执行 Agent", task.execution_owner === "main" ? "Main Agent" : task.execution_owner === "delivery_agent" ? "交付 Agent" : task.execution_owner === "task_agent" ? "Task Agent" : "未声明");
+    field(container, "对话策略", task.conversation_policy ?? "未声明");
+    field(container, "交付策略", task.delivery_policy ?? "未声明");
+    field(container, "调度状态", task.dispatch_readiness === "blocked" ? `不可调度：${task.dispatch_diagnostics?.map((item) => item.message).join("；") || "未知原因"}` : task.dispatch_readiness === "ready" ? "可调度" : "未知");
+    const pr = context.safeExternal(task.pr?.url ?? null);
+    if (pr) field(container, "子 PR", link("查看 PR", pr));
+    if (task.requirements_path) field(container, "任务要求", link("查看 Markdown", `api/document/task-${encodeURIComponent(task.id)}`));
+    for (const follow of data.follow_prs.filter((item) => item.origin_task_id === task.id)) {
+      const url = context.safeExternal(follow.pr.url);
+      field(container, "Follow PR", url ? link(context.labels[follow.state] ?? follow.state, url) : context.labels[follow.state] ?? follow.state);
+    }
+    restore();
+  };
+
+  const showGroup = (group: Group, focusedAtomId: string | null = null): void => {
+    const data = context.getData();
+    if (!data) return;
+    const tasks = data.tasks.filter((task) => task.group_id === group.id);
+    const historicalTaskIds = [...new Set(data.actual_intervals.filter((row) => row.group_id === group.id).map((row) => row.task_id))];
+    const executionState = groupExecutionVisualState(group.state, group.coordination_execution?.state);
+    const { container, restore } = begin("group", group.id, group.title, context.labels[executionState] ?? executionState);
+    const groupAtoms = group.atoms ?? group.planned_atoms;
+    field(container, "原子任务", atomList(groupAtoms, (index) => {
+      const atom = groupAtoms![index]!;
+      const previous = groupAtoms![index - 1];
+      const items: DependencyTooltipItem[] = previous ? [{ name: previous.title, state: "", status: previous.status, completedAt: previous.completed_at }] : [];
+      if (atom.lifecycle_stage) {
+        const titles = { workspace_ready: "父分支准备就绪", pr_created: "父 PR 已创建", pr_merged: "父 PR 已合并", closed: "交付单元收口" };
+        const status = group.lifecycle?.[atom.lifecycle_stage];
+        items.push({ name: titles[atom.lifecycle_stage], state: "", status: status === "passed" ? "completed" : status === "failed" ? "blocked" : "planned", completedAt: group.lifecycle_completed_at?.[atom.lifecycle_stage] });
+      }
+      return items;
+    }, focusedAtomId, { kind: "group", id: group.id }));
+    if (group.coordination_execution?.state === "waiting") field(container, "协调等待", group.coordination_execution.reason ?? "等待贡献任务");
+    if (group.coordination_execution?.state === "blocked") field(container, "协调阻塞", group.coordination_execution.reason ?? "未知原因");
+    field(container, "交付协调者", coordinatorValue(group));
+    field(container, "运行就绪", readinessValue(group));
+    field(container, "任务数", `${tasks.length} 个任务`);
+    if (historicalTaskIds.length) field(container, "历史执行任务", historicalTaskIds.map((id) => data.tasks.find((task) => task.id === id)?.title ?? id).join("、"));
+    field(container, "持续时间", durationValue(group.started_at ?? null, group.finished_at ?? null));
+    if (context.profileContext) {
+      const profileContext = context.profileContext();
+      field(container, "执行配置", createProfileEditor(profileContext, "group", group.id, group.execution_profile ?? null, group.effective_execution_profile ?? data.orchestration.execution_profile ?? null, data.profile_read_only ? "当前视图只读或尚未迁移" : group.profile_freeze_reason ?? (group.agent_thread_id ? "对话已创建" : null)));
+    }
+    field(container, "交付单元对话", group.agent_thread_id ? link("打开对话", conversationUrl(group.agent_thread_id)) : "尚未创建");
+    field(container, "交付 Agent", group.delivery_unit_kind === "bootstrap" ? "Main Agent（Bootstrap 特例）" : group.delivery_agent_readiness === "bound" ? "已绑定" : "未绑定");
+    field(container, "调度状态", group.dispatch_readiness === "blocked" ? `不可调度：${group.dispatch_diagnostics?.map((item) => item.message).join("；") || "未知原因"}` : group.dispatch_readiness === "ready" ? "可调度" : "未知");
+    const pr = context.safeExternal(group.parent_pr?.url ?? null);
+    field(container, "父 PR", pr ? link("查看 PR", pr) : "尚未创建");
+    if (group.requirements_path) field(container, "交付单元要求", link("查看 Markdown", `api/document/group-${encodeURIComponent(group.id)}`));
+    restore();
+  };
+
+  const taskPreview = (task: Task): HTMLElement => {
+    const data = context.getData();
+    const group = data?.groups.find((item) => item.id === task.group_id);
+    const executionGroups = [...new Set(data?.actual_intervals.filter((row) => row.task_id === task.id).map((row) => row.group_id) ?? [])].map((id) => data?.groups.find((item) => item.id === id)?.title ?? id);
+    return renderTaskPreview({ title: task.title, state: context.labelTask(task), kind: taskKindLabel(task.kind), group: group?.title ?? task.group_id, startedAt: task.started_at ?? "", finishedAt: task.finished_at ?? "", duration: formatDuration(task.started_at, task.finished_at), blocker: task.blocker, ...(executionGroups.length > 1 ? { executionGroups: executionGroups.join("、") } : {}) });
+  };
+
+  const groupPreview = (group: Group): HTMLElement => {
+    const executionState = groupExecutionVisualState(group.state, group.coordination_execution?.state);
+    const atoms = group.atoms ?? group.planned_atoms ?? [];
+    const atom = atoms.find((item) => item.status === "running" || item.status === "blocked") ?? atoms.find((item) => item.status === "planned");
+    const progress = atoms.length === 0 ? "未配置原子任务" : atoms.every((item) => item.status === "completed") ? `${atoms.length}/${atoms.length} · 已完成` : atom ? `${atoms.indexOf(atom) + 1}/${atoms.length} · ${atom.title}` : `0/${atoms.length} · 待开始`;
+    return renderGroupPreview({ title: group.title, state: context.labels[executionState] ?? executionState, atomProgress: progress, duration: formatDuration(group.started_at ?? null, group.finished_at ?? null), conversation: group.delivery_unit_kind === "bootstrap" ? "主对话" : group.agent_thread_id ? "已创建" : "尚未创建", parentPr: context.safeExternal(group.parent_pr?.url ?? null) ? "已关联" : "尚未创建" });
+  };
+  const showMilestone = (nodeId: string, group: Group): void => {
+    const data = context.getData();
+    const node = data?.nodes.find((item) => item.id === nodeId && item.kind === "milestone");
+    const focusedAtomId = group.atoms?.find((atom) => atom.lifecycle_stage === "pr_merged")?.id ?? group.planned_atoms?.find((atom) => atom.lifecycle_stage === "pr_merged")?.id ?? null;
+    showGroup(group, focusedAtomId);
+    const summary = document.getElementById("details-summary");
+    if (summary && node) summary.replaceChildren(text("div", node.label, "detail-title"), text("div", "里程碑", "detail-state"));
+  };
+  return { clearDetails, showTask, showGroup, showMilestone, taskPreview, groupPreview };
+}

package/toolkit/skills/multi-task-flow/web/execution-range.ts

@@ -0,0 +1,26 @@
+export type ExecutionRange = { start: string | null; end: string | null };
+
+export type ExecutionInterval = {
+  start: string | null;
+  end: string | null;
+};
+
+export function rangeFromIntervals(
+  intervals: readonly ExecutionInterval[],
+): ExecutionRange {
+  const starts = intervals
+    .map((interval) => interval.start)
+    .filter((value): value is string => value !== null && Number.isFinite(Date.parse(value)));
+  const start = starts.length
+    ? starts.sort((left, right) => Date.parse(left) - Date.parse(right))[0] ?? null
+    : null;
+  const complete = intervals.length > 0 && intervals.every(
+    (interval) => interval.end !== null && Number.isFinite(Date.parse(interval.end)),
+  );
+  const ends = complete
+    ? intervals
+      .map((interval) => interval.end!)
+      .sort((left, right) => Date.parse(right) - Date.parse(left))
+    : [];
+  return { start, end: ends[0] ?? null };
+}

package/toolkit/skills/multi-task-flow/web/focus.ts

@@ -0,0 +1,9 @@
+export function focusAfterRerender(primary: HTMLElement | null, fallback: HTMLElement | null): void {
+  const isFocusable = (element: HTMLElement | null): element is HTMLElement => Boolean(element?.isConnected && !element.hidden && !element.closest("[hidden]") && (element.matches("button, a[href], input, select, textarea, [tabindex]:not([tabindex='-1'])") || element.getAttribute("role") === "button"));
+  const target = isFocusable(primary) ? primary : isFocusable(fallback) ? fallback : null;
+  target?.focus({ preventScroll: true });
+}
+
+export function firstVisibleElement(root: ParentNode, selector: string): HTMLElement | null {
+  return [...root.querySelectorAll<HTMLElement>(selector)].find((element) => !element.closest("[hidden]")) ?? null;
+}

package/toolkit/skills/multi-task-flow/web/graph-layout.ts

@@ -0,0 +1,89 @@
+import ELK, { type ElkNode, type ElkExtendedEdge } from 'elkjs/lib/elk.bundled.js';
+import type { GraphProjection, GraphProjectionNode } from './graph-projection';
+
+export const CARD_WIDTH = 184;
+export const CARD_HEIGHT = 76;
+
+export function cardSize(title: string): {width:number;height:number} {
+  const glyphWidth = (char:string) => /[\u2e80-\uffff]/u.test(char) ? 15 : /[A-ZMW]/.test(char) ? 10 : /\s/.test(char) ? 4 : 8;
+  const textWidth = Array.from(title).reduce((sum,char)=>sum+glyphWidth(char),0);
+  const width = Math.max(136,Math.min(CARD_WIDTH,Math.ceil(textWidth+24)));
+  let lines=1,used=0;
+  for(const char of title){const next=glyphWidth(char);if(used+next>width-24){lines++;used=0;}used+=next;}
+  return {width,height:Math.max(CARD_HEIGHT,38+lines*21)};
+}
+export type Direction = 'DOWN' | 'RIGHT';
+export type PlacedNode = { node: GraphProjectionNode; x: number; y: number; width: number; height: number };
+export type RoutedEdge = { id: string; source: string; target: string; path: string };
+export type GraphLayout = { nodes: PlacedNode[]; edges: RoutedEdge[]; width: number; height: number };
+const elk = new ELK();
+
+// Keep the semantic projection intact. Each dependency gets its own two ports.
+export async function layoutProjection(projection: GraphProjection, direction: Direction): Promise<GraphLayout> {
+  const ports = new Map<string, NonNullable<ElkNode['ports']>>();
+  for (const n of projection.nodes) ports.set(n.id, []);
+  const edges: ElkExtendedEdge[] = projection.edges.map(e => {
+    const source = `port:${e.id}:source`, target = `port:${e.id}:target`;
+    ports.get(e.source)?.push({ id: source, width: 0, height: 0, layoutOptions: { 'elk.port.side': direction === 'DOWN' ? 'SOUTH' : 'EAST' } });
+    ports.get(e.target)?.push({ id: target, width: 0, height: 0, layoutOptions: { 'elk.port.side': direction === 'DOWN' ? 'NORTH' : 'WEST' } });
+    return { id: e.id, sources: [source], targets: [target] };
+  });
+  const nonEmptyGroups = new Set(projection.nodes.map(n => n.parentId).filter((id): id is string => !!id));
+  // ELK gives empty compound nodes zero size; keep their graph endpoint visible.
+  const entries = new Map(projection.nodes.map(n => [n.id, {
+    id: n.id, ...(n.nodeKind === 'group' ? (nonEmptyGroups.has(n.id) ? {} : { width: CARD_WIDTH, height: CARD_HEIGHT }) : cardSize(n.title)),
+    ports: ports.get(n.id),
+    layoutOptions: n.nodeKind === 'group' ? { 'elk.padding': '[top=38,left=16,bottom=16,right=16]' } : { 'elk.portConstraints': 'FIXED_SIDE' },
+    ...(n.nodeKind === 'group' ? {children: []} : {}),
+  } as ElkNode]));
+  const children: ElkNode[] = [];
+  for (const n of projection.nodes) {
+    const child = entries.get(n.id)!;
+    const parent = n.parentId ? entries.get(n.parentId) : undefined;
+    if (parent?.children) parent.children.push(child); else children.push(child);
+  }
+  const input = { id: 'layout-root', children, edges, layoutOptions: {
+    'elk.algorithm': 'layered', 'elk.direction': direction,
+    'elk.edgeRouting': 'ORTHOGONAL', 'elk.hierarchyHandling': 'INCLUDE_CHILDREN',
+    'elk.spacing.nodeNode': '16', 'elk.layered.spacing.nodeNodeBetweenLayers': '24',
+    'elk.layered.spacing.edgeNodeBetweenLayers': '8', 'elk.spacing.edgeEdge': '6',
+    'elk.layered.nodePlacement.strategy': 'BRANDES_KOEPF',
+    'elk.layered.nodePlacement.bk.fixedAlignment': 'BALANCED',
+    'elk.layered.mergeEdges': 'true',
+    'elk.layered.considerModelOrder.strategy': 'NODES_AND_EDGES',
+    'elk.padding': '[top=12,left=12,bottom=12,right=12]',
+  }};
+  const result = await elk.layout<ElkNode>(JSON.parse(JSON.stringify(input)));
+  const nodes: PlacedNode[] = [], routed: RoutedEdge[] = [];
+  const nodeById = new Map(projection.nodes.map(n => [n.id, n]));
+  const edgeById = new Map(projection.edges.map(e => [e.id, e]));
+  const offsets = new Map<string, {x:number;y:number}>();
+  const collect = (container: ElkNode, x:number, y:number) => {
+    offsets.set(container.id, {x,y});
+    for (const child of container.children ?? []) collect(child,x+(child.x??0),y+(child.y??0));
+  };
+  collect(result,0,0);
+  const visit = (container: ElkNode, x: number, y: number) => {
+    for (const e of container.edges ?? []) {
+      // ELK may retain an edge on the root while routing it in a nested container.
+      const origin = offsets.get((e as ElkExtendedEdge & {container?:string}).container ?? container.id) ?? {x,y};
+      const edge = edgeById.get(e.id);
+      if (!edge) continue;
+      const path = (e.sections ?? []).map(s => {
+        const points = [s.startPoint, ...(s.bendPoints ?? []), s.endPoint];
+        return points.map((p, i) => `${i ? 'L' : 'M'} ${p.x + origin.x} ${p.y + origin.y}`).join(' ');
+      }).join(' ');
+      if (!path) throw new Error(`No route for dependency ${e.id}`);
+      routed.push({ id: e.id, source: edge.source, target: edge.target, path });
+    }
+    for (const child of container.children ?? []) {
+      const px = x + (child.x ?? 0), py = y + (child.y ?? 0);
+      const node = nodeById.get(child.id);
+      if (node) nodes.push({ node, x: px, y: py, width: child.width!, height: child.height! });
+      visit(child, px, py);
+    }
+  };
+  visit(result, 0, 0);
+  if (routed.length !== projection.edges.length) throw new Error('Incomplete dependency routes');
+  return { nodes, edges: routed, width: result.width ?? 0, height: result.height ?? 0 };
+}