qgraphflow 0.0.6 → 0.0.7

package/skills/q-flow/assets/viewer/src/i18n-messages.json

@@ -1,5 +1,7 @@
 {
   "zh-CN": {
+    "Layout suggestions": "布局优化建议",
+    "Arrange this view to improve connector clearance and spacing. Existing positions are preserved until then.": "整理此图可改善连线间距与布局；整理前保留现有位置。",
     "Architecture": "架构图",
     "Flowchart": "流程图",
     "Sequence": "时序图",
@@ -161,7 +163,27 @@
     "In-progress state": "进行中状态",
     "In-progress state: warm to cool as it advances": "进行中状态：由暖到冷表示推进顺序",
     "Transition": "转移",
-    "Self-transition: handled without leaving the state": "自转移：留在原状态内处理的事件"
+    "Self-transition: handled without leaving the state": "自转移：留在原状态内处理的事件",
+    "Key points": "要点",
+    "Show key points": "显示要点",
+    "Hide key points": "隐藏要点",
+    "Component relations": "组件关系",
+    "Platform capabilities": "平台能力总览",
+    "Engineering layers": "工程分层总览",
+    "Overview text": "总览正文",
+    "Badges": "徽章",
+    "Badge type": "徽章类型",
+    "Add badge": "添加徽章",
+    "Remove badge": "移除徽章",
+    "Status": "状态",
+    "Version": "版本",
+    "Requirement": "接入要求",
+    "Overview aligned": "总览已对齐",
+    "Section": "分区",
+    "Cancelled": "已取消",
+    "Component relationship architecture": "组件关系架构图",
+    "Platform capability architecture": "平台能力架构图",
+    "Engineering layer architecture": "工程分层架构图"
   },
   "ja": {
     "Architecture": "アーキテクチャ",
@@ -325,7 +347,29 @@
     "In-progress state": "進行中の状態",
     "In-progress state: warm to cool as it advances": "進行中の状態：進むにつれて暖色から寒色へ",
     "Transition": "遷移",
-    "Self-transition: handled without leaving the state": "自己遷移：状態を離れずに処理するイベント"
+    "Self-transition: handled without leaving the state": "自己遷移：状態を離れずに処理するイベント",
+    "Key points": "要点",
+    "Show key points": "要点を表示",
+    "Hide key points": "要点を隠す",
+    "Component relations": "コンポーネント関係",
+    "Platform capabilities": "プラットフォーム機能",
+    "Engineering layers": "プロジェクト階層",
+    "Overview text": "概要本文",
+    "Badges": "バッジ",
+    "Badge type": "バッジの種類",
+    "Add badge": "バッジを追加",
+    "Remove badge": "バッジを削除",
+    "Status": "状態",
+    "Version": "バージョン",
+    "Requirement": "要件",
+    "Overview aligned": "概要を整列しました",
+    "Section": "セクション",
+    "Cancelled": "キャンセルしました",
+    "Component relationship architecture": "コンポーネント関係アーキテクチャ図",
+    "Platform capability architecture": "プラットフォーム機能アーキテクチャ図",
+    "Engineering layer architecture": "プロジェクト階層アーキテクチャ図",
+    "Layout suggestions": "レイアウトの提案",
+    "Arrange this view to improve connector clearance and spacing. Existing positions are preserved until then.": "このビューを整列すると、接続線の余白と間隔を改善できます。それまでは現在の位置が保持されます。"
   },
   "ko": {
     "Architecture": "아키텍처",
@@ -489,7 +533,29 @@
     "In-progress state": "진행 중인 상태",
     "In-progress state: warm to cool as it advances": "진행 중인 상태: 진행될수록 따뜻한 색에서 차가운 색으로",
     "Transition": "전이",
-    "Self-transition: handled without leaving the state": "자기 전이: 상태를 벗어나지 않고 처리하는 이벤트"
+    "Self-transition: handled without leaving the state": "자기 전이: 상태를 벗어나지 않고 처리하는 이벤트",
+    "Key points": "요점",
+    "Show key points": "요점 보기",
+    "Hide key points": "요점 숨기기",
+    "Component relations": "구성 요소 관계",
+    "Platform capabilities": "플랫폼 기능",
+    "Engineering layers": "프로젝트 계층",
+    "Overview text": "개요 본문",
+    "Badges": "배지",
+    "Badge type": "배지 유형",
+    "Add badge": "배지 추가",
+    "Remove badge": "배지 제거",
+    "Status": "상태",
+    "Version": "버전",
+    "Requirement": "요구 사항",
+    "Overview aligned": "개요 정렬 완료",
+    "Section": "섹션",
+    "Cancelled": "취소됨",
+    "Component relationship architecture": "구성 요소 관계 아키텍처",
+    "Platform capability architecture": "플랫폼 기능 아키텍처",
+    "Engineering layer architecture": "엔지니어링 계층 아키텍처",
+    "Layout suggestions": "레이아웃 제안",
+    "Arrange this view to improve connector clearance and spacing. Existing positions are preserved until then.": "이 보기를 정리하여 연결선의 여백과 간격을 개선하세요. 정리하기 전까지 기존 위치가 유지됩니다."
   },
   "de": {
     "Architecture": "Architektur",
@@ -653,7 +719,29 @@
     "In-progress state": "Zustand in Bearbeitung",
     "In-progress state: warm to cool as it advances": "Zustand in Bearbeitung: von warm nach kalt, je weiter er fortschreitet",
     "Transition": "Übergang",
-    "Self-transition: handled without leaving the state": "Selbstübergang: Ereignis, das im Zustand bleibt"
+    "Self-transition: handled without leaving the state": "Selbstübergang: Ereignis, das im Zustand bleibt",
+    "Key points": "Kernaussagen",
+    "Show key points": "Kernaussagen anzeigen",
+    "Hide key points": "Kernaussagen ausblenden",
+    "Component relations": "Komponentenbeziehungen",
+    "Platform capabilities": "Plattformfunktionen",
+    "Engineering layers": "Projektebenen",
+    "Overview text": "Übersichtstext",
+    "Badges": "Abzeichen",
+    "Badge type": "Abzeichentyp",
+    "Add badge": "Abzeichen hinzufügen",
+    "Remove badge": "Abzeichen entfernen",
+    "Status": "Status",
+    "Version": "Version",
+    "Requirement": "Anforderung",
+    "Overview aligned": "Übersicht ausgerichtet",
+    "Section": "Abschnitt",
+    "Cancelled": "Abgebrochen",
+    "Component relationship architecture": "Komponentenarchitektur",
+    "Platform capability architecture": "Plattformfähigkeitsarchitektur",
+    "Engineering layer architecture": "Schichtenarchitektur",
+    "Layout suggestions": "Layoutvorschläge",
+    "Arrange this view to improve connector clearance and spacing. Existing positions are preserved until then.": "Ordnen Sie diese Ansicht an, um Abstände der Verbindungslinien zu verbessern. Bis dahin bleiben die bisherigen Positionen erhalten."
   },
   "fr": {
     "Architecture": "Architecture",
@@ -817,7 +905,29 @@
     "In-progress state": "État en cours",
     "In-progress state: warm to cool as it advances": "État en cours : du chaud au froid à mesure qu’il avance",
     "Transition": "Transition",
-    "Self-transition: handled without leaving the state": "Auto-transition : événement traité sans quitter l’état"
+    "Self-transition: handled without leaving the state": "Auto-transition : événement traité sans quitter l’état",
+    "Key points": "Points clés",
+    "Show key points": "Afficher les points clés",
+    "Hide key points": "Masquer les points clés",
+    "Component relations": "Relations entre composants",
+    "Platform capabilities": "Capacités de la plateforme",
+    "Engineering layers": "Couches du projet",
+    "Overview text": "Texte de présentation",
+    "Badges": "Badges",
+    "Badge type": "Type de badge",
+    "Add badge": "Ajouter un badge",
+    "Remove badge": "Supprimer le badge",
+    "Status": "Statut",
+    "Version": "Version",
+    "Requirement": "Exigence",
+    "Overview aligned": "Présentation alignée",
+    "Section": "Section",
+    "Cancelled": "Annulé",
+    "Component relationship architecture": "Architecture des composants",
+    "Platform capability architecture": "Architecture des capacités",
+    "Engineering layer architecture": "Architecture en couches",
+    "Layout suggestions": "Suggestions de disposition",
+    "Arrange this view to improve connector clearance and spacing. Existing positions are preserved until then.": "Réorganisez cette vue pour améliorer les dégagements et les espacements des connecteurs. Les positions actuelles sont conservées jusque-là."
   },
   "es": {
     "Architecture": "Arquitectura",
@@ -981,7 +1091,29 @@
     "In-progress state": "Estado en curso",
     "In-progress state: warm to cool as it advances": "Estado en curso: de cálido a frío a medida que avanza",
     "Transition": "Transición",
-    "Self-transition: handled without leaving the state": "Autotransición: evento atendido sin salir del estado"
+    "Self-transition: handled without leaving the state": "Autotransición: evento atendido sin salir del estado",
+    "Key points": "Puntos clave",
+    "Show key points": "Mostrar puntos clave",
+    "Hide key points": "Ocultar puntos clave",
+    "Component relations": "Relaciones entre componentes",
+    "Platform capabilities": "Capacidades de la plataforma",
+    "Engineering layers": "Capas del proyecto",
+    "Overview text": "Texto del resumen",
+    "Badges": "Insignias",
+    "Badge type": "Tipo de insignia",
+    "Add badge": "Añadir insignia",
+    "Remove badge": "Eliminar insignia",
+    "Status": "Estado",
+    "Version": "Versión",
+    "Requirement": "Requisito",
+    "Overview aligned": "Resumen alineado",
+    "Section": "Sección",
+    "Cancelled": "Cancelado",
+    "Component relationship architecture": "Arquitectura de componentes",
+    "Platform capability architecture": "Arquitectura de capacidades",
+    "Engineering layer architecture": "Arquitectura por capas",
+    "Layout suggestions": "Sugerencias de diseño",
+    "Arrange this view to improve connector clearance and spacing. Existing positions are preserved until then.": "Organiza esta vista para mejorar la separación y el espacio de los conectores. Las posiciones actuales se conservan hasta entonces."
   },
   "ru": {
     "Architecture": "Архитектура",
@@ -1145,7 +1277,29 @@
     "In-progress state": "Состояние в процессе",
     "In-progress state: warm to cool as it advances": "Состояние в процессе: от тёплого цвета к холодному по мере продвижения",
     "Transition": "Переход",
-    "Self-transition: handled without leaving the state": "Петля: событие обрабатывается без выхода из состояния"
+    "Self-transition: handled without leaving the state": "Петля: событие обрабатывается без выхода из состояния",
+    "Key points": "Ключевые выводы",
+    "Show key points": "Показать ключевые выводы",
+    "Hide key points": "Скрыть ключевые выводы",
+    "Component relations": "Связи компонентов",
+    "Platform capabilities": "Возможности платформы",
+    "Engineering layers": "Слои проекта",
+    "Overview text": "Текст обзора",
+    "Badges": "Метки",
+    "Badge type": "Тип метки",
+    "Add badge": "Добавить метку",
+    "Remove badge": "Удалить метку",
+    "Status": "Статус",
+    "Version": "Версия",
+    "Requirement": "Требование",
+    "Overview aligned": "Обзор выровнен",
+    "Section": "Раздел",
+    "Cancelled": "Отменено",
+    "Component relationship architecture": "Архитектура компонентов",
+    "Platform capability architecture": "Архитектура возможностей платформы",
+    "Engineering layer architecture": "Слоистая архитектура",
+    "Layout suggestions": "Рекомендации по размещению",
+    "Arrange this view to improve connector clearance and spacing. Existing positions are preserved until then.": "Упорядочьте эту схему, чтобы улучшить зазоры и расстояния между связями. До этого текущие позиции сохраняются."
   },
   "pt": {
     "Architecture": "Arquitetura",
@@ -1309,6 +1463,28 @@
     "In-progress state": "Estado em andamento",
     "In-progress state: warm to cool as it advances": "Estado em andamento: do quente ao frio conforme avança",
     "Transition": "Transição",
-    "Self-transition: handled without leaving the state": "Autotransição: evento tratado sem sair do estado"
+    "Self-transition: handled without leaving the state": "Autotransição: evento tratado sem sair do estado",
+    "Key points": "Pontos-chave",
+    "Show key points": "Mostrar pontos-chave",
+    "Hide key points": "Ocultar pontos-chave",
+    "Component relations": "Relações entre componentes",
+    "Platform capabilities": "Capacidades da plataforma",
+    "Engineering layers": "Camadas do projeto",
+    "Overview text": "Texto da visão geral",
+    "Badges": "Emblemas",
+    "Badge type": "Tipo de emblema",
+    "Add badge": "Adicionar emblema",
+    "Remove badge": "Remover emblema",
+    "Status": "Estado",
+    "Version": "Versão",
+    "Requirement": "Requisito",
+    "Overview aligned": "Visão geral alinhada",
+    "Section": "Seção",
+    "Cancelled": "Cancelado",
+    "Component relationship architecture": "Arquitetura de componentes",
+    "Platform capability architecture": "Arquitetura de capacidades",
+    "Engineering layer architecture": "Arquitetura em camadas",
+    "Layout suggestions": "Sugestões de disposição",
+    "Arrange this view to improve connector clearance and spacing. Existing positions are preserved until then.": "Organize esta vista para melhorar as folgas e os espaçamentos das ligações. As posições atuais são preservadas até lá."
   }
 }

package/skills/q-flow/assets/viewer/src/layout-compaction.js

@@ -0,0 +1,123 @@
+import { groupHeadingBoxes, occupiedBox, visibleEdgeLabel } from './edge-routing.js';
+import { diagramTypeOf, getDiagram } from './diagrams/registry.js';
+import { layoutLimits, layoutTargets } from './layout-spacing.js';
+import { groupHeadingLayout, estimateLabelSize } from './text-layout.js';
+
+// Tighten actual ownership subtrees bottom-up; never infer ownership from containment.
+export function tightenGroups(graph) {
+  const groups=graph.groups??[], limits=layoutLimits(getDiagram(diagramTypeOf(graph))), done=new Set();
+  const fit=group=>{
+    if(done.has(group.id))return; done.add(group.id);
+    const children=groups.filter(g=>g.parentId===group.id); children.forEach(fit);
+    const members=[...children,...graph.nodes.filter(n=>n.groupId===group.id)]; if(!members.length)return;
+    const heading=groupHeadingLayout(group), top=heading.height+limits.groupHeadingGap;
+    const x=Math.max(0,Math.min(...members.map(n=>n.position.x))-limits.groupInset), y=Math.max(0,Math.min(...members.map(n=>n.position.y))-top);
+    const right=Math.max(...members.map(n=>n.position.x+n.size.width))+limits.groupInset, bottom=Math.max(...members.map(n=>n.position.y+n.size.height))+limits.groupInset;
+    group.position={x,y}; group.size={width:Math.max(right-x,heading.width+2*limits.groupInset),height:bottom-y};
+  };
+  groups.forEach(fit);return graph;
+}
+
+// Sweep genuinely empty horizontal/vertical slabs. A subtree moves intact when the cut is outside it;
+// a boundary spanning the cut shrinks with its members. Routing validates the reclaimed channel.
+export function* compactCandidates(input) {
+  const type=diagramTypeOf(input); if(type==='sequence')return;
+  const diagram=getDiagram(type), limits=layoutLimits(diagram), target=layoutTargets(diagram);
+  yield* compactChannels(input,type,limits,target);
+  if (['architecture','deployment','er','dataflow'].includes(type)) {
+    const groups=input.groups??[];
+    const descendants=id=>{const ids=new Set([id]);for(let size=0;size!==ids.size;){size=ids.size;for(const group of groups)if(ids.has(group.parentId))ids.add(group.id);}return ids;};
+    // Ownership frames can occupy unused space beside a connected frame while their subtree remains rigid.
+    // Authored ranks/order and type-specific partitions are retained; the caller rechecks semantic geometry.
+    if (type === 'architecture' && !input.layout?.primaryPath?.length) {
+      const roots = groups.filter(g=>!g.parentId).map(item=>{const ids=descendants(item.id);return {item,groups:groups.filter(g=>ids.has(g.id)),nodes:input.nodes.filter(n=>ids.has(n.groupId))};});
+      const owner = new Map(roots.flatMap(unit=>unit.nodes.map(node=>[node.id,unit]))), proposals=[];
+      const estimate = graph => {
+        const all=[...graph.nodes,...(graph.groups??[])], byId=new Map(graph.nodes.map(n=>[n.id,n]));
+        const area=(Math.max(...all.map(n=>n.position.x+n.size.width))-Math.min(...all.map(n=>n.position.x)))*(Math.max(...all.map(n=>n.position.y+n.size.height))-Math.min(...all.map(n=>n.position.y)));
+        const nodeArea=graph.nodes.reduce((sum,n)=>sum+n.size.width*n.size.height,0),unit=Math.sqrt(nodeArea/graph.nodes.length);
+        const length=graph.edges.reduce((sum,e)=>{const a=byId.get(e.source),b=byId.get(e.target);return sum+Math.abs(a.position.x+a.size.width/2-b.position.x-b.size.width/2)+Math.abs(a.position.y+a.size.height/2-b.position.y-b.size.height/2);},0);
+        return area/nodeArea+length/(Math.max(1,graph.edges.length)*unit);
+      };
+      for (const unit of roots) {
+        if(unit.nodes.some(n=>n.layout?.order!==undefined||n.layout?.rank!==undefined))continue;
+        const peers=new Set(input.edges.flatMap(e=>owner.get(e.source)===unit?[owner.get(e.target)]:owner.get(e.target)===unit?[owner.get(e.source)]:[]).filter(p=>p&&p!==unit));
+        for(const peer of peers) for(const axis of ['x','y']) for(const after of [false,true]) {
+          const across=axis==='x'?'y':'x',extent=axis==='x'?'width':'height', gap=target.nodeGap;
+          const position={...peer.item.position,[axis]:after?peer.item.position[axis]+peer.item.size[extent]+gap:peer.item.position[axis]-unit.item.size[extent]-gap};
+          if(position.x<0||position.y<0)continue;
+          const rect={...position,...unit.item.size};
+          if(roots.some(other=>other!==unit&&rect.x<other.item.position.x+other.item.size.width+limits.groupGap&&other.item.position.x<rect.x+rect.width+limits.groupGap&&rect.y<other.item.position.y+other.item.size.height+limits.groupGap&&other.item.position.y<rect.y+rect.height+limits.groupGap))continue;
+          const ids=new Set([...unit.groups,...unit.nodes].map(n=>n.id)),dx=position.x-unit.item.position.x,dy=position.y-unit.item.position.y;
+          const geometry=items=>items.map(n=>({id:n.id,size:n.size,position:ids.has(n.id)?{x:n.position.x+dx,y:n.position.y+dy}:n.position}));
+          const score=estimate({...input,nodes:geometry(input.nodes),groups:geometry(groups)});
+          if(score<estimate(input)-.001)proposals.push({ids,dx,dy,score,id:unit.item.id+':'+peer.item.id+':'+axis+':'+after});
+        }
+      }
+      proposals.sort((a,b)=>a.score-b.score||a.id.localeCompare(b.id));
+      for(const proposal of proposals.slice(0,12)) {
+        const graph=structuredClone(input);
+        for(const member of [...graph.nodes,...graph.groups])if(proposal.ids.has(member.id)){member.position.x+=proposal.dx;member.position.y+=proposal.dy;}
+        yield graph;
+      }
+    }
+    const rows=new Map();
+    for(const item of [...groups,...input.nodes].sort((a,b)=>a.id.localeCompare(b.id))) {
+      const group=groups.includes(item), scope=group?item.parentId:item.groupId;
+      const key=`${scope??''}:${item.position.y}`;
+      const ids=group?descendants(item.id):new Set();
+      const nodes=group?input.nodes.filter(n=>ids.has(n.groupId)):[item];
+      const unit={item,groups:group?groups.filter(g=>ids.has(g.id)):[],nodes};
+      rows.set(key,[...(rows.get(key)??[]),unit]);
+    }
+    for(const [,items] of [...rows].sort(([a],[b])=>a.localeCompare(b))) {
+      if(items.length<2 || items.some(unit=>unit.nodes.some(n=>n.layout?.order!==undefined)))continue;
+      const row=items.sort((a,b)=>a.item.position.x-b.item.position.x||a.item.id.localeCompare(b.item.id));
+      for(let i=0;i<row.length;i++)for(let j=i+1;j<row.length;j++) {
+        const graph=structuredClone(input), byId=new Map([...graph.nodes,...(graph.groups??[])].map(n=>[n.id,n]));
+        const order=[...row];[order[i],order[j]]=[order[j],order[i]];
+        let x=row[0].item.position.x;
+        for(let k=0;k<order.length;k++) {
+          const unit=order[k],dx=x-unit.item.position.x;
+          for(const member of [...unit.groups,...unit.nodes])byId.get(member.id).position.x+=dx;
+          const gap=k<row.length-1?Math.max(target.nodeGap,row[k+1].item.position.x-row[k].item.position.x-row[k].item.size.width):0;
+          x+=unit.item.size.width+gap;
+        }
+        yield graph;
+      }
+    }
+  }
+}
+
+function* compactChannels(input,type,limits,target) {
+  const tight=tightenGroups(structuredClone(input));
+  if(JSON.stringify(tight.groups)!==JSON.stringify(input.groups))yield tight;
+  const boxes=[...input.nodes.map(n=>occupiedBox(n,type)),...(input.groups??[]).flatMap(groupHeadingBoxes)];
+  const gaps=[];
+  for(const [axis,extent] of [['x','width'],['y','height']]) {
+    const labelSpan=Math.max(0,...input.edges.map(e=>estimateLabelSize(visibleEdgeLabel(e,type,input.meta.locale))[extent]));
+    const layerGap = axis === 'y' && ['class', 'state', 'flowchart'].includes(type) ? target.layerGap : target.nodeGap;
+    const keep=Math.max(layerGap,labelSpan+2*limits.labelGap);
+    const intervals=boxes.map(r=>[r[axis],r[axis]+r[extent]]).sort((a,b)=>a[0]-b[0]);
+    let end=intervals[0]?.[1]??0;
+    for(const [start,last] of intervals) {
+      if(start-end>keep+1)gaps.push({axis,extent,cut:start,remove:start-end-keep});
+      end=Math.max(end,last);
+    }
+  }
+  gaps.sort((a,b)=>b.remove-a.remove||a.axis.localeCompare(b.axis)||a.cut-b.cut);
+  for(const gap of gaps) for(const fraction of [1,.5]) {
+    const graph=structuredClone(input), delta=gap.remove*fraction;
+    const follow = value => value >= gap.cut ? value-delta : value > gap.cut-delta ? gap.cut-delta : value;
+    for(const node of graph.nodes)if(node.position[gap.axis]>=gap.cut)node.position[gap.axis]-=delta;
+    for(const edge of graph.edges) {
+      if(edge.route?.via) edge.route.via=edge.route.via.map(point=>({...point,[gap.axis]:follow(point[gap.axis])}));
+      if(edge.route?.labelAt) edge.route.labelAt={...edge.route.labelAt,[gap.axis]:follow(edge.route.labelAt[gap.axis])};
+    }
+    for(const group of graph.groups??[]) {
+      if(group.position[gap.axis]>=gap.cut)group.position[gap.axis]-=delta;
+      else if(group.position[gap.axis]+group.size[gap.extent]>=gap.cut)group.size[gap.extent]-=delta;
+    }
+    yield graph;
+  }
+}

package/skills/q-flow/assets/viewer/src/layout-measure.js

@@ -1,8 +1,8 @@
+import { hasOverviewContent, overviewCardLayout } from './architecture-overview.js';
 import { getDiagram } from './diagrams/registry.js';
 import { sequenceHeaderHeight } from './diagrams/sequence.js';
-import { cardTextLayout, layoutText } from './text-layout.js';
-import { TYPOGRAPHY, kindLabels } from './visual-style.js';
-import { translate } from './i18n.js';
+import { CARD, cardSourceText, cardTag, cardTextLayout, layoutText } from './text-layout.js';
+import { TYPOGRAPHY } from './visual-style.js';
 import { STATE_ACTIONS, STATE_ACTION_INSET, stateActivities } from './diagrams/state.js';
 
 // System fonts vary: reserve width beyond the estimate, then verify actual glyphs in the browser.
@@ -10,6 +10,7 @@ const singleLineWidth = (text, font) => Math.ceil(layoutText(String(text ?? '').
 const rounded = size => Object.fromEntries(Object.entries(size).map(([key, value]) => [key, Math.ceil(value)]));
 
 export function minimumNodeSize(node, type, locale = 'en') {
+  if (type === 'architecture' && hasOverviewContent(node)) return { width: 300, height: overviewCardLayout(node, node.size?.width ?? 300).minHeight };
   const diagram = getDiagram(type), title = singleLineWidth(node.label, TYPOGRAPHY.title), body = singleLineWidth(node.subtitle, TYPOGRAPHY.body);
   if (type === 'state' && ['initial', 'final'].includes(node.kind)) {
     if (!node.subtitle) return { width: 28, height: 28 };
@@ -22,7 +23,8 @@ export function minimumNodeSize(node, type, locale = 'en') {
     const heading = layoutText(node.label, width - 24, TYPOGRAPHY.title, 29), subtitle = layoutText(node.subtitle, width - 24, TYPOGRAPHY.body, 23.2);
     return rounded({ width, height: Math.max(72, heading.height + (subtitle.height ? 5 + subtitle.height : 0) + 16) + stateActivities({ ...node, size: { width, height: 0 } }).height });
   }
-  if (diagram.sequence || node.kind === 'actor') return { width: Math.max(160, title + 28, body + 28), height: diagram.sequence ? sequenceHeaderHeight(node) + 48 : 104 + (node.subtitle ? 24 : 0) };
+  if (diagram.sequence) { const width = Math.max(160, Math.min(280, Math.max(title, body) + 28)); return { width, height: sequenceHeaderHeight({ ...node, size: { width } }) + 48 }; }
+  if (node.kind === 'actor') return { width: Math.max(160, title + 28, body + 28), height: diagram.sequence ? sequenceHeaderHeight(node) + 48 : 104 + (node.subtitle ? 24 : 0) };
   if (diagram.cardinalities) {
     const fields = node.fields.map(field => {
       const name = singleLineWidth(field.name, TYPOGRAPHY.body), type = singleLineWidth(field.type, TYPOGRAPHY.body);
@@ -35,13 +37,17 @@ export function minimumNodeSize(node, type, locale = 'en') {
     return rounded({ width: Math.max(240, title + 26, body + 26, ...[...attributes, ...methods].map(value => singleLineWidth(value, TYPOGRAPHY.body) + 26)),
       height: TYPOGRAPHY.classHeader + (node.subtitle ? 24 : 0) + (attributes.length ? attributes.length * TYPOGRAPHY.classRow + 13 : 30) + (methods.length ? methods.length * TYPOGRAPHY.classRow + 13 : 30) });
   }
-  const size = { width: Math.max(240, Math.min(480, Math.max(title, body) + 60)), height: 100 };
   if (diagram.cardLayout) {
-    const inset = diagram.contentInset?.({ ...node, size }) ?? 0;
-    size.width = Math.max(size.width, singleLineWidth(translate(locale, kindLabels[node.kind] ?? node.kind), TYPOGRAPHY.small) + 70 + 2 * inset);
-    size.height = Math.max(100, cardTextLayout({ ...node, size: { ...size, width: size.width - 2 * (diagram.contentInset?.({ ...node, size }) ?? 0) } }).minHeight);
+    // One-line title beside the plate and kind tag where the width cap allows; longer text wraps and the card grows taller.
+    const corner = diagram.cardCorner?.(node) ?? 0;
+    const needed = Math.max(title + cardTag(node, locale).width + CARD.tagGap + corner, body, singleLineWidth(cardSourceText(node), TYPOGRAPHY.small)) + CARD.textX + CARD.pad;
+    // Outlines with slanted sides (hexagon, parallelogram, octagon) inset the text on both sides.
+    const inset = diagram.contentInset?.({ ...node, size: { width: Math.min(CARD.maxWidth, needed + 56), height: 0 } }) ?? 0;
+    const size = { width: Math.max(240, Math.min(CARD.maxWidth, needed + 2 * inset)), height: 0 };
+    size.height = cardTextLayout({ ...node, size: { ...size, width: size.width - 2 * (diagram.contentInset?.({ ...node, size }) ?? 0) } }, locale, false, corner).minHeight;
     return rounded(size);
   }
+  const size = { width: Math.max(240, Math.min(480, Math.max(title, body) + 60)), height: type === 'flowchart' ? 72 : 100 };
   const textArea = diagram.textArea ?? (node => ({ width: node.size.width - 36, height: node.size.height - 20 }));
   // All supported safety regions grow monotonically with height. Bounded expansion also handles diamond/ellipse insets.
   for (let i = 0; i < 16; i++) {

package/skills/q-flow/assets/viewer/src/layout-policy.js

@@ -0,0 +1,6 @@
+// Persist only the layout version; callers of preserve never upgrade it implicitly.
+export const LAYOUT_VERSION = 'templates-v4-clearance-compact-elkjs-0.11.0';
+export const currentLayout = graph => /^templates-v([4-9]|\d{2,})-/.test(graph.layout?.version ?? '');
+export const alignedLayout = graph => /^templates-v([3-9]|\d{2,})-/.test(graph.layout?.version ?? '');
+export const tieredLayout = graph => /^templates-v([2-9]|\d{2,})-/.test(graph.layout?.version ?? '');
+export const layoutWeights = Object.freeze({ bends: .5, crossings: 2 });

package/skills/q-flow/assets/viewer/src/layout-quality.js

@@ -1,7 +1,13 @@
+import { currentLayout, alignedLayout, tieredLayout } from './layout-policy.js';
+import { clearanceLimits, nodeClearance, boundaryClearance } from './route-clearance.js';
+import { deploymentTierOf } from './layout-semantics.js';
+import { presentationGraph } from './presentation-graph.js';
+import { isArchitectureOverview } from './view-identity.js';
+import { overviewGeometryErrors, overviewSections } from './architecture-overview.js';
 import { auditGraphLayout, boxDistance, occupiedBox, graphBounds, segmentCrossesBox } from './edge-routing.js';
-import { diagramTypeOf, getDiagram } from './diagrams/registry.js';
-import { cardTextLayout, layoutText, groupHeadingLayout } from './text-layout.js';
-import { LAYOUT_LIMITS } from './layout-spacing.js';
+import { cardText, compactCards, diagramTypeOf, getDiagram } from './diagrams/registry.js';
+import { layoutText, groupHeadingLayout } from './text-layout.js';
+import { layeredDown, layoutLimits } from './layout-spacing.js';
 import { minimumNodeSize } from './layout-measure.js';
 import { validateGraph } from './graph-validation.js';
 
@@ -14,6 +20,8 @@ export function qualityFailure(graph, phase, message, diagnostics = []) {
   if (!diagnostics.length) diagnostics = (String(message).includes('\n- ') ? String(message).split('\n- ').slice(1) : [String(message)]).map(detail => {
     const elements = ['nodes', 'edges', 'groups'].flatMap(key => (Array.isArray(graph?.[key]) ? graph[key] : []).filter((item, index) => item && typeof item === 'object' && (
       detail.includes(`${key}[${index}]`) || new RegExp(`(^|[^\\w.-])${String(item.id).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}($|[^\\w.-])`).test(detail))));
+    for (const edge of elements.filter(item => item.source && item.target)) elements.push(...(graph.nodes ?? []).filter(node => node.id === edge.source || node.id === edge.target));
+    elements.push(...overviewSections(graph ?? {}).filter(item => String(detail).includes(item.id)));
     return { ruleId: `${phase}.invalid`, severity: 'error', diagramType: diagramTypeOf(graph),
       elementIds: elements.map(item => item.id), measured: detail, required: `Valid ${phase} content and complete notation`,
       bounds: elements.filter(item => item.position && item.size).map(item => ({ ...item.position, ...item.size })),
@@ -26,18 +34,19 @@ export function qualityFailure(graph, phase, message, diagnostics = []) {
   } });
 }
 
-export function requireDiagramQuality(graph) {
+export function requireDiagramQuality(graph, options = {}) {
   const semantic = validateGraph(graph, { inputOnly: true });
   const geometry = semantic.length ? [] : validateGraph(graph, { audit: false });
-  const audit = semantic.length || geometry.length ? null : auditLayoutQuality(graph);
+  const audit = semantic.length || geometry.length ? null : auditLayoutQuality(graph, options);
   const errors = [...semantic, ...geometry, ...(audit?.errors ?? [])];
   const phases = { semantic: { status: semantic.length ? 'failed' : 'passed' }, geometry: { status: semantic.length ? 'not-checked' : errors.length ? 'failed' : 'passed' }, rendering: { status: 'not-checked' } };
   if (errors.length) throw qualityFailure(graph, semantic.length ? 'semantic' : 'geometry', `Diagram quality failed:\n- ${errors.join('\n- ')}`, audit?.diagnostics ?? []);
   return { ...phases, diagnostics: audit.diagnostics };
 }
 
-export function auditLayoutQuality(graph) {
-  const legacy = auditGraphLayout(graph), type = diagramTypeOf(graph), diagram = getDiagram(type), limits = LAYOUT_LIMITS;
+export function auditLayoutQuality(graph, { strictEdgeIds = null } = {}) {
+  graph = presentationGraph(graph);
+  const legacy = auditGraphLayout(graph), type = diagramTypeOf(graph), diagram = getDiagram(type), limits = isArchitectureOverview(graph) ? { ...layoutLimits(diagram), nodeGap: 14, labelGap: 6, parallelGap: 8, groupInset: 22, groupHeadingGap: 14 } : layoutLimits(diagram);
   const diagnostics = [...legacy.diagnostics, ...legacy.crossings];
   const issue = (ruleId, ids, measured, required, boxes, remediation) => diagnostics.push({ ruleId, severity: 'error', diagramType: type, elementIds: ids, measured, required, bounds: boxes, remediation });
   const nodeBoxes = new Map(graph.nodes.map(node => [node.id, occupiedBox(node, type)]));
@@ -60,7 +69,7 @@ export function auditLayoutQuality(graph) {
       const branches = graph.edges.filter(edge => edge.source === node.id && edge.target !== node.id);
       return { node, branches, sides: new Set(branches.map(edge => legacy.routes.get(edge.id).sourceSide)) };
     }).filter(item => item.branches.length >= 2) : [];
-    const vertical = !['er', 'deployment', 'dataflow', 'usecase'].includes(type);
+    const vertical = layeredDown(type, graph.layout);
     const coordinate = vertical ? 'y' : 'x', dimension = vertical ? 'height' : 'width';
     // A layout folded into top-down columns continues at the top of the next column: a successor that sits entirely to the
     // right of its predecessor keeps the notation's reading direction; a path or hierarchy step must also start higher.
@@ -70,29 +79,34 @@ export function auditLayoutQuality(graph) {
       if (distance + .001 < limits.nodeGap) issue('semantic.rank', [first.id, second.id], distance, limits.nodeGap, [nodeBoxes.get(first.id), nodeBoxes.get(second.id)], 'Keep declared ranks in separate layers along the reading direction.');
     }
     if (vertical && graph.nodes.length > 5 && Math.max(...graph.nodes.map(node => node.position.y)) < Math.min(...graph.nodes.map(node => node.position.y + node.size.height))) issue('semantic.single-row', graph.nodes.map(node => node.id), 1, 'multiple rows', [...nodeBoxes.values()], 'Arrange responsibility layers or wrap peer nodes; tiny y offsets do not create another row.');
+    if (type === 'deployment' && (tieredLayout(graph) || graph.layout?.strategy?.startsWith('template-runtime-tiers') || graph.nodes.some(node => node.layout?.tier))) for (const parent of graph.nodes) for (const child of graph.nodes) {
+      if (deploymentTierOf(parent) >= deploymentTierOf(child)) continue;
+      const distance = child.position.y - parent.position.y - parent.size.height;
+      if (distance + .001 < limits.nodeGap) issue('semantic.deployment-tier', [parent.id, child.id], distance, limits.nodeGap, [nodeBoxes.get(parent.id), nodeBoxes.get(child.id)], 'Keep external, application, infrastructure and data tiers from top to bottom.');
+    }
     if (type === 'class') for (const edge of graph.edges.filter(edge => ['inheritance', 'implementation'].includes(edge.kind))) {
       const child = nodeById.get(edge.source), parent = nodeById.get(edge.target), distance = child.position.y - parent.position.y - parent.size.height;
-      if (distance + .001 < limits.nodeGap && !continues(parent, child, true)) issue('semantic.class-hierarchy', [edge.id, parent.id, child.id], distance, limits.nodeGap, [nodeBoxes.get(parent.id), nodeBoxes.get(child.id)], 'Place the parent class or interface above its child or implementation, or continue the hierarchy at the top of the next column.');
+      if (distance + .001 < limits.nodeGap) issue('semantic.class-hierarchy', [edge.id, parent.id, child.id], distance, limits.nodeGap, [nodeBoxes.get(parent.id), nodeBoxes.get(child.id)], 'Place the parent class or interface above its child or implementation.');
     }
     if (type === 'state') for (const symbol of graph.nodes.filter(node => ['initial', 'final'].includes(node.kind))) {
       for (const state of graph.nodes.filter(node => !['initial', 'final'].includes(node.kind))) {
         const distance = symbol.kind === 'initial' ? state.position.y - symbol.position.y - symbol.size.height : symbol.position.y - state.position.y - state.size.height;
-        const continued = symbol.kind === 'initial' ? continues(symbol, state, false) : continues(state, symbol, false);
-        if (distance + .001 < limits.nodeGap && !continued) issue('semantic.state-endpoint', [symbol.id, state.id], distance, limits.nodeGap, [nodeBoxes.get(symbol.id), nodeBoxes.get(state.id)], 'Keep initial symbols above the lifecycle and final symbols below it; a column fold continues the lifecycle at the top of the next column.');
+        if (distance + .001 < limits.nodeGap) issue('semantic.state-endpoint', [symbol.id, state.id], distance, limits.nodeGap, [nodeBoxes.get(symbol.id), nodeBoxes.get(state.id)], 'Keep initial symbols above the lifecycle and final symbols below it.');
       }
     }
     for (const [source, target] of primary) {
       const distance = target.position[coordinate] - source.position[coordinate] - source.size[dimension];
-      if (distance + .001 < limits.nodeGap && !continues(source, target, true)) issue('semantic.primary-path', [source.id, target.id], distance, limits.nodeGap, [nodeBoxes.get(source.id), nodeBoxes.get(target.id)], 'Keep the declared or unambiguous main path directed downwards; a column fold continues it at the top of the next column.');
+      if (distance + .001 < limits.nodeGap && (graph.layout?.strategy?.startsWith('template-') || !continues(source, target, true))) issue('semantic.primary-path', [source.id, target.id], distance, limits.nodeGap, [nodeBoxes.get(source.id), nodeBoxes.get(target.id)], 'Keep the declared or unambiguous main path directed downwards; a column fold continues it at the top of the next column.');
     }
     for (const { node, branches, sides } of decisions) {
       if (!['left', 'right'].every(side => sides.has(side))) issue('semantic.branch-sides', [node.id, ...branches.map(edge => edge.id)], [...sides], ['left', 'right'], [nodeBoxes.get(node.id)], 'Give alternatives separate left and right corridors while retaining their real targets and merges.');
     }
   }
+  const classicCard = !compactCards(graph);
   for (let i = 0; i < graph.nodes.length; i++) {
     const node = graph.nodes[i], rect = nodeBoxes.get(node.id), minimum = minimumNodeSize(node, type, graph.meta.locale);
     if (diagram.cardLayout) {
-      const inset = diagram.contentInset?.(node) ?? 0, required = Math.max(100, cardTextLayout({ ...node, size: { ...node.size, width: node.size.width - inset * 2 } }).minHeight);
+      const required = cardText(node, type, graph.meta.locale, classicCard).minHeight;
       if (node.size.height < required) issue('text.node-height', [node.id], node.size.height, required, [rect], 'Increase height to keep full title and subtitle at 20/16px.');
     } else if (diagram.textArea && node.kind !== 'actor' && !['initial', 'final'].includes(node.kind)) {
       const area = diagram.textArea(node), title = layoutText(node.label, area.width, 20, 29), body = layoutText(node.subtitle, area.width, 16, 23.2), required = title.height + (body.height ? body.height + 5 : 0);
@@ -125,9 +139,16 @@ export function auditLayoutQuality(graph) {
   }
   for (let i = 0; i < graph.edges.length; i++) {
     const edge = graph.edges[i], route = legacy.routes.get(edge.id), parts = segments(route);
+    if (!diagram.sequence && alignedLayout(graph) && route.label) {
+      const point = route.labelPoint;
+      const distance = Math.min(...parts.map(([a, b]) => Math.hypot(point.x - Math.max(Math.min(a.x, b.x), Math.min(Math.max(a.x, b.x), point.x)), point.y - Math.max(Math.min(a.y, b.y), Math.min(Math.max(a.y, b.y), point.y)))));
+      if (distance > .001) issue('label.on-route', [edge.id], distance, 0, [route.labelBox], 'Keep the relationship label centred on its own straight segment.');
+    }
     if (!diagram.sequence) for (const [point, neighbor, hint] of [[route.points[0], route.points[1], edge.route?.via?.[0]], [route.points.at(-1), route.points.at(-2), edge.route?.via?.at(-1)]]) {
       const distance = Math.hypot(point.x - neighbor.x, point.y - neighbor.y), required = diagram.endpointStub ?? limits.endpoint;
-      const length = hint && distance ? Math.min(distance, ((hint.x - point.x) * (neighbor.x - point.x) + (hint.y - point.y) * (neighbor.y - point.y)) / distance) : distance;
+      // A monotone direct segment has no turn at its guide; a bent path must still reserve the authored first-turn clearance.
+      const projection = hint && distance ? ((hint.x - point.x) * (neighbor.x - point.x) + (hint.y - point.y) * (neighbor.y - point.y)) / distance : distance;
+      const length = route.points.length === 2 && projection >= 0 ? distance : Math.min(distance, projection);
       if (length + .001 < required) issue('route.endpoint-stub', [edge.id], length, required, [{ ...point, width: 0, height: 0 }], 'Reserve a straight outward segment for the endpoint symbol.');
     }
     for (const other of graph.edges.slice(i + 1)) {
@@ -158,7 +179,32 @@ export function auditLayoutQuality(graph) {
       for (const other of groups.slice(i + 1)) if (group.parentId === other.parentId && boxDistance(rect, bounds(other)) + .001 < limits.groupGap) issue('group.sibling-gap', [group.id, other.id], boxDistance(rect, bounds(other)), limits.groupGap, [rect, bounds(other)], 'Separate sibling boundaries.');
     }
   }
+  const routeMetrics = [];
+  if (!diagram.sequence) {
+    const clearance = clearanceLimits(graph), probes = graph.nodes.map(node => ({ node, probe: nodeClearance(node, type) }));
+    for (const edge of graph.edges) {
+      const route = legacy.routes.get(edge.id), parts = segments(route), strict = currentLayout(graph) || strictEdgeIds?.has(edge.id);
+      const report = (ruleId, ids, measured, required, boxes, remediation, hard = true) => diagnostics.push({ ruleId, severity: hard && strict ? 'error' : 'warning', diagramType: type, elementIds: ids, measured, required, bounds: boxes, remediation });
+      let minimum = Infinity, hugging = 0;
+      for (const {node,probe} of probes) {
+        const distances = parts.flatMap(([a,b], index) => (node.id === edge.source && index === 0 || node.id === edge.target && index === parts.length-1) ? [] : [probe(a,b)]);
+        const distance = Math.min(...distances); minimum = Math.min(minimum,distance);
+        if (distance + .001 < clearance.node) report('route.node-clearance',[edge.id,node.id],distance,clearance.node,[nodeBoxes.get(node.id)],'Arrange this relation with clear space around the visible component.');
+      }
+      for (const group of graph.groups ?? []) {
+        const near = parts.map(([a,b])=>boundaryClearance(a,b,group)).filter(item=>item.distance+.001<clearance.boundary);
+        hugging += near.reduce((sum,item)=>sum+item.length,0);
+        if (near.length) report('route.boundary-clearance',[edge.id,group.id],Math.min(...near.map(item=>item.distance)),clearance.boundary,[bounds(group)],'Cross the boundary perpendicularly or leave a clear parallel channel.');
+      }
+      const length = parts.reduce((sum,[a,b])=>sum+Math.abs(a.x-b.x)+Math.abs(a.y-b.y),0), start=route.points[0], end=route.points.at(-1);
+      const direct=Math.abs(start.x-end.x)+Math.abs(start.y-end.y), bends=Math.max(0,route.points.length-2), detour=direct ? length/direct : null;
+      const shortSegments=parts.slice(1,-1).filter(([a,b])=>Math.abs(a.x-b.x)+Math.abs(a.y-b.y)<clearance.node-.001).length;
+      routeMetrics.push({edgeId:edge.id,length,bends,detour,minimumClearance:Number.isFinite(minimum)?minimum:null,boundaryHugging:hugging,shortSegments});
+      if (bends>4 || shortSegments || edge.source!==edge.target && detour>1.8) report('route.complexity',[edge.id],{bends,shortSegments,detour},{bends:4,shortSegments:0,detour:1.8},[{x:Math.min(...route.points.map(p=>p.x)),y:Math.min(...route.points.map(p=>p.y)),width:Math.max(...route.points.map(p=>p.x))-Math.min(...route.points.map(p=>p.x)),height:Math.max(...route.points.map(p=>p.y))-Math.min(...route.points.map(p=>p.y))}],'Try a simpler corridor or arrange nearby components; necessary detours remain supported.',false);
+    }
+  }
   // Existing shape/fragment/marker checks stay blocking; new rules carry structured locations above.
+  for (const detail of overviewGeometryErrors(graph, legacy.routes)) { const elements = overviewSections(graph).filter(item => detail.includes(item.id)); issue('overview.section', elements.map(item => item.id), detail, 'Complete section text and contained items', elements.map(bounds), 'Expand and re-layout the identified section without removing facts.'); }
   const errors = [...diagnostics.filter(item => item.severity === 'error').map(item => `${item.ruleId}: ${item.elementIds.join(', ')} (${JSON.stringify(item.measured)}; required ${JSON.stringify(item.required)})`)];
-  return { ...legacy, errors, diagnostics, bounds: graphBounds(graph, legacy.routes) };
+  return { ...legacy, errors, diagnostics, routeMetrics, bounds: graphBounds(graph, legacy.routes) };
 }