Skip to content

HK-hub/AgentSkills / archify

archify

Flagged

Create polished, validated architecture, workflow, sequence, data-flow, and lifecycle/state diagrams as explorable standalone HTML with inline SVG, dark/light themes, semantic navigation, optional trace motion, an optional 1200×630 Share Card PNG, and PNG/JPEG/WebP/SVG/WebM export. Accept plain-language requirements or pasted Mermaid flowchart, sequenceDiagram, and stateDiagram input; inspect repository evidence when the diagram must reflect real code. Use when the user asks to visualize system architecture, infrastructure, cloud/security/network topology, technical workflows, approval or CI/CD flows, API call sequences, request lifecycles, data pipelines, ETL/ELT, data lineage, state machines, or to convert/beautify Mermaid. Prefer typed JSON IR renderers and deterministic validation; deliver static output by default, enable motion only when requested, and use optional post-commit opening only for an interactive local handoff.

FileKindSize
LICENSEother1.1 KB
SKILL.mdskill md70.7 KB
assets/template.htmlother585.9 KB
bin/archify.mjsscript47.6 KB
bin/open-artifact.mjsscript2.2 KB
bin/preview.mjsscript23.5 KB
delta/architecture-delta.mjsscript68.8 KB
examples/agent-run.lifecycle.jsonconfig4.3 KB
examples/agent-tool-call.workflow.jsonconfig6.3 KB
examples/async-job-roundtrip.sequence.jsonconfig4.4 KB
examples/cache-miss-request.sequence.jsonconfig4.3 KB
examples/checkout-platform.base.architecture.jsonconfig2.3 KB
examples/checkout-platform.head.architecture.jsonconfig2.4 KB
examples/dataflow-product-analytics.htmlother602.5 KB
examples/deployment-release.lifecycle.jsonconfig4.3 KB
examples/event-stream.dataflow.jsonconfig5.4 KB
examples/incident-response.workflow.jsonconfig5.3 KB
examples/lifecycle-agent-run.htmlother595.6 KB
examples/product-analytics.dataflow.jsonconfig5.6 KB
examples/production-deployment.architecture.jsonconfig5.4 KB
examples/release-delivery.workflow.jsonconfig5.1 KB
examples/sequence-cache-miss-request.htmlother598.6 KB
examples/web-app-rendered.htmlother596.6 KB
examples/web-app.architecture.jsonconfig3.8 KB
examples/workflow-agent-tool-call-rendered.htmlother604.8 KB
package-lock.jsonmanifest2.5 KB
package.jsonmanifest1016 B
recipes/scenarios.mjsscript27.2 KB
renderers/architecture/grid.mjsscript2.0 KB
renderers/architecture/render-architecture.mjsscript20.7 KB
renderers/dataflow/README.mdmarkdown3.6 KB
renderers/dataflow/render-dataflow.mjsscript16.9 KB
renderers/lifecycle/README.mdmarkdown4.5 KB
renderers/lifecycle/render-lifecycle.mjsscript20.8 KB
renderers/sequence/README.mdmarkdown3.8 KB
renderers/sequence/render-sequence.mjsscript17.1 KB
renderers/shared/cli.mjsscript9.4 KB
renderers/shared/diagnostics.mjsscript4.0 KB
renderers/shared/engineering-profiles.mjsscript6.8 KB
renderers/shared/generated-validators.mjsscript278.4 KB
renderers/shared/geometry.mjsscript44.0 KB
renderers/shared/layout-report.mjsscript1015 B
renderers/shared/repository-evidence.mjsscript11.2 KB
renderers/shared/utils.mjsscript8.1 KB
renderers/shared/validator.mjsscript3.4 KB
renderers/workflow/README.mdmarkdown4.9 KB
renderers/workflow/render-workflow.mjsscript25.2 KB
schemas/README.mdmarkdown6.6 KB
schemas/architecture.schema.jsonconfig5.5 KB
schemas/common.schema.jsonconfig1.7 KB
schemas/dataflow.schema.jsonconfig5.1 KB
schemas/lifecycle.schema.jsonconfig5.5 KB
schemas/sequence.schema.jsonconfig4.3 KB
schemas/workflow.schema.jsonconfig7.4 KB
scripts/check-render-output.mjsscript28.8 KB
scripts/generate-validators.mjsscript2.3 KB
scripts/render-examples.mjsscript1.2 KB
test/animation.test.mjsscript8.2 KB
test/architecture-delta.test.mjsscript22.2 KB
test/authored-reachability.test.mjsscript4.4 KB
test/automatic-port-spread.test.mjsscript8.7 KB
test/chapter-delta-preview.test.mjsscript7.3 KB
test/chapter-handoff.test.mjsscript4.9 KB
test/chapter-rail.test.mjsscript4.2 KB
test/cli.test.mjsscript27.4 KB
test/cursor-onboarding.test.mjsscript3.5 KB
test/degraded.test.mjsscript6.8 KB
test/delivery-contract.test.mjsscript1.5 KB
test/diagram-guide.test.mjsscript4.7 KB
test/engineering-profile.test.mjsscript10.0 KB
test/finder.test.mjsscript5.3 KB
test/fixtures/v1-baseline/agent-run.lifecycle.jsonconfig3.5 KB
test/fixtures/v1-baseline/agent-tool-call.workflow.jsonconfig5.2 KB
test/fixtures/v1-baseline/cache-miss-request.sequence.jsonconfig3.5 KB
test/fixtures/v1-baseline/product-analytics.dataflow.jsonconfig4.7 KB
test/fixtures/v1-baseline/web-app.architecture.jsonconfig3.0 KB
test/gallery.test.mjsscript6.2 KB
test/generate-validators.test.mjsscript1.4 KB
test/geometry.test.mjsscript25.5 KB
test/golden.mjsscript8.0 KB
test/grid.test.mjsscript1.7 KB
test/guide-page.test.mjsscript2.0 KB
test/guide.test.mjsscript3.3 KB
test/guided-views.test.mjsscript7.3 KB
test/intent-trace.test.mjsscript4.8 KB
test/landing.test.mjsscript5.4 KB
test/layout-rules.test.mjsscript23.8 KB
test/motion-governor.test.mjsscript6.3 KB
test/open-artifact.test.mjsscript3.1 KB
test/presentation.test.mjsscript3.2 KB
test/preset-tryon.test.mjsscript4.7 KB
test/preview-contract.test.mjsscript2.0 KB
test/preview.test.mjsscript21.9 KB
test/proof-aperture.test.mjsscript4.5 KB
test/reach-share-card.test.mjsscript8.1 KB
test/readme-showcase.test.mjsscript8.9 KB
test/real-repository-proof.test.mjsscript5.1 KB
test/relationship-direct-explorer.test.mjsscript6.2 KB
test/relationship-lens.test.mjsscript7.0 KB
test/relationship-permalink.test.mjsscript6.3 KB
test/relationship-pulse.test.mjsscript6.6 KB
test/render-output-checks.test.mjsscript21.2 KB
test/repair-receipt.test.mjsscript6.7 KB
test/repository-evidence.test.mjsscript9.1 KB
test/route-journey.test.mjsscript8.0 KB
test/route-probe.test.mjsscript6.1 KB
test/route-share-card.test.mjsscript9.5 KB
test/semantic-camera.test.mjsscript4.7 KB
test/semantic-flow.test.mjsscript4.7 KB
test/semantic-legend-gateway.test.mjsscript6.1 KB
test/semantic-lens.test.mjsscript5.4 KB
test/semantic-passport.test.mjsscript5.6 KB
test/semantic-radar.test.mjsscript5.5 KB
test/semantic-zoom.test.mjsscript4.2 KB
test/settled-flow.test.mjsscript5.2 KB
test/share-card-export.test.mjsscript6.8 KB
test/skill-metadata.test.mjsscript1.2 KB
test/start-page.test.mjsscript4.5 KB
test/story-beat-navigator.test.mjsscript6.4 KB
test/story-carrier.test.mjsscript4.7 KB
test/story-director-strip.test.mjsscript5.2 KB
test/story-follow-camera.test.mjsscript5.8 KB
test/story-horizon.test.mjsscript5.2 KB
test/story-moment-link.test.mjsscript5.5 KB
test/story-shelf.test.mjsscript4.7 KB
test/story-trail.test.mjsscript4.1 KB
test/v1-compatibility.test.mjsscript6.1 KB
test/webm-artifact.smoke.mjsscript83.3 KB

renderers/shared/geometry.mjs

View on GitHub
// Geometry helpers shared by all typed renderers. Every function here is
// pure; renderers own their layout tables and pass measured rects
// ({x, y, width, height, cx, cy}) in.

import { recordDiagnostic } from './diagnostics.mjs';

// In degraded mode (no ajv) a type-wrong top-level field reaches the renderer.
// Coerce non-arrays to [] so the module-level Maps build without throwing and
// the friendly validator checks (which run later) report the real problem.
export function asArray(value) {
  return Array.isArray(value) ? value : [];
}

// A computed coordinate must be a finite number; NaN/undefined would silently
// write `<rect x="NaN">` into the output. Used by the validators as a backstop.
export function isFinitePoint(...coords) {
  return coords.every((c) => Number.isFinite(c));
}

export function rectsOverlap(a, b, gap = 0) {
  return !(
    a.x + a.width + gap <= b.x ||
    b.x + b.width + gap <= a.x ||
    a.y + a.height + gap <= b.y ||
    b.y + b.height + gap <= a.y
  );
}

export function segmentIntersectsRect(segment, rect, gap = 0) {
  const box = {
    x1: rect.x - gap,
    y1: rect.y - gap,
    x2: rect.x + rect.width + gap,
    y2: rect.y + rect.height + gap
  };
  const [a, b] = [segment.start, segment.end];
  if (pointInBox(a, box) || pointInBox(b, box)) return true;
  return (
    segmentsIntersect(a, b, [box.x1, box.y1], [box.x2, box.y1]) ||
    segmentsIntersect(a, b, [box.x2, box.y1], [box.x2, box.y2]) ||
    segmentsIntersect(a, b, [box.x2, box.y2], [box.x1, box.y2]) ||
    segmentsIntersect(a, b, [box.x1, box.y2], [box.x1, box.y1])
  );
}

export function segmentRectClearance(segment, rect) {
  if (!segment || !rect) return null;
  const { start, end } = segment;
  if (!Array.isArray(start) || !Array.isArray(end) || start.length !== 2 || end.length !== 2) return null;
  if (!isFinitePoint(...start, ...end, rect.x, rect.y, rect.width, rect.height)) return null;
  if (rect.width < 0 || rect.height < 0) return null;
  if (segmentIntersectsRect(segment, rect)) return 0;

  const corners = [
    [rect.x, rect.y],
    [rect.x + rect.width, rect.y],
    [rect.x + rect.width, rect.y + rect.height],
    [rect.x, rect.y + rect.height],
  ];
  return Math.min(
    pointRectDistance(start, rect),
    pointRectDistance(end, rect),
    ...corners.map((corner) => pointSegmentDistance(corner, start, end)),
  );
}

export function segmentRectIntersectionLength(segment, rect) {
  if (!segment || !rect) return null;
  const { start, end } = segment;
  if (!Array.isArray(start) || !Array.isArray(end) || start.length !== 2 || end.length !== 2) return null;
  if (!isFinitePoint(...start, ...end, rect.x, rect.y, rect.width, rect.height)) return null;
  if (rect.width < 0 || rect.height < 0) return null;

  const dx = end[0] - start[0];
  const dy = end[1] - start[1];
  const length = Math.hypot(dx, dy);
  if (length <= 0.0000001) return 0;
  const bounds = [
    [-dx, start[0] - rect.x],
    [dx, rect.x + rect.width - start[0]],
    [-dy, start[1] - rect.y],
    [dy, rect.y + rect.height - start[1]],
  ];
  let enter = 0;
  let leave = 1;
  for (const [direction, distance] of bounds) {
    if (Math.abs(direction) <= 0.0000001) {
      if (distance < -0.0000001) return 0;
      continue;
    }
    const ratio = distance / direction;
    if (direction < 0) enter = Math.max(enter, ratio);
    else leave = Math.min(leave, ratio);
    if (enter > leave + 0.0000001) return 0;
  }
  return length * Math.max(0, leave - enter);
}

export function collectLabelRouteClearance({ labels, routedRelations, threshold }) {
  if (!Number.isFinite(threshold) || threshold < 0) return [];
  const routeCandidates = asArray(routedRelations).map((entry, fallbackIndex) => {
    const relation = entry?.relation || entry;
    const points = normalizeRoutePoints(entry?.points || relation?.routePoints);
    if (!relation || points.length < 2) return null;
    return {
      relation,
      relationIndex: Number.isInteger(entry?.relationIndex) ? entry.relationIndex : fallbackIndex,
      points,
    };
  }).filter(Boolean);
  const seenRoutes = new Set();
  const routes = routeCandidates.filter((route) => {
    const identity = relationshipIdentity(route.relation, route.relationIndex);
    if (seenRoutes.has(identity)) return false;
    seenRoutes.add(identity);
    return true;
  });
  const hits = [];
  const seenLabels = new Set();

  for (const [fallbackIndex, label] of asArray(labels).entries()) {
    const rect = label?.rect || label;
    if (!rect || !isFinitePoint(rect.x, rect.y, rect.width, rect.height) || rect.width < 0 || rect.height < 0) continue;
    const relationIndex = Number.isInteger(label?.relationIndex) ? label.relationIndex : fallbackIndex;
    const labelIdentity = relationshipIdentity(label?.relation, relationIndex);
    if (seenLabels.has(labelIdentity)) continue;
    seenLabels.add(labelIdentity);
    for (const route of routes) {
      if (relationIndex === route.relationIndex || sameRelationship(label?.relation, route.relation)) continue;
      let nearest = null;
      for (let segmentIndex = 0; segmentIndex < route.points.length - 1; segmentIndex += 1) {
        const start = route.points[segmentIndex];
        const end = route.points[segmentIndex + 1];
        const clearance = segmentRectClearance({ start, end }, rect);
        if (clearance == null) continue;
        if (!nearest || clearance < nearest.clearance) {
          nearest = {
            clearance,
            intersectionLength: segmentRectIntersectionLength({ start, end }, rect),
            segmentIndex,
            start,
            end,
          };
        }
      }
      if (!nearest || nearest.clearance + 0.0001 >= threshold) continue;
      hits.push({
        label,
        labelRelation: label?.relation,
        labelRelationIndex: relationIndex,
        otherRelation: route.relation,
        otherRelationIndex: route.relationIndex,
        rect,
        ...nearest,
        threshold,
      });
    }
  }
  return hits;
}

function relationshipIdentity(relation, relationIndex) {
  if (relation?.key !== undefined) return `key:${relation.key}`;
  if (relation?.id) return `id:${relation.from || ''}\u0000${relation.to || ''}\u0000${relation.id}`;
  return `index:${relationIndex}`;
}

function sameRelationship(left, right) {
  if (!left || !right) return false;
  if (left === right) return true;
  if (left.key !== undefined && right.key !== undefined) return left.key === right.key;
  return Boolean(left.id && right.id && left.id === right.id && left.from === right.from && left.to === right.to);
}

function relationshipSubject(diagramType, relationCollection, relationIndex, relation) {
  return {
    diagramType,
    collection: relationCollection,
    index: relationIndex,
    ...(relation?.id ? { id: relation.id } : {}),
    ...(relation?.from ? { from: relation.from } : {}),
    ...(relation?.to ? { to: relation.to } : {}),
  };
}

// One mechanical quality gate for every renderer-owned relationship path.
// A renderer supplies its semantic obstacle set; source/target boxes are
// always exempt because paths are expected to terminate on their boundaries.
// Containers, lifelines, and other intentionally pass-through geometry should
// simply not be supplied as obstacles.
export function cleanFlowProblems({
  relations,
  obstacles,
  pathFor,
  diagramType,
  relationCollection,
  obstacleKind,
  profile,
  clearance = 2,
  routeHint = 'adjust fromSide/toSide, set route/via or channel coordinates, or move the obstacle'
}) {
  // A relationship hidden behind an unrelated opaque node changes the
  // diagram's meaning, so this is a correctness invariant rather than an
  // opt-in composition preference. Keep it active even when the author omits
  // quality_profile; standard/showcase still control stricter visual budgets.
  const problems = [];
  const obstacleList = [...obstacles];
  const obstacleIds = new Set(obstacleList.map((obstacle) => obstacle?.id));
  for (const [relationIndex, relation] of asArray(relations).entries()) {
    if (!relation || typeof relation.from !== 'string' || typeof relation.to !== 'string') continue;
    if (!obstacleIds.has(relation.from) || !obstacleIds.has(relation.to)) continue;
    const points = pathFor(relation)?.points;
    if (!Array.isArray(points) || points.length < 2) continue;
    if (!points.every((point) => Array.isArray(point) && point.length === 2 && isFinitePoint(...point))) continue;

    const endpointIds = new Set([relation.from, relation.to]);
    for (const obstacle of obstacleList) {
      if (!obstacle || endpointIds.has(obstacle.id)) continue;
      if (!isFinitePoint(obstacle.x, obstacle.y, obstacle.width, obstacle.height)) continue;
      let hitSegment = -1;
      for (let segmentIndex = 0; segmentIndex < points.length - 1; segmentIndex += 1) {
        if (segmentIntersectsRect({ start: points[segmentIndex], end: points[segmentIndex + 1] }, obstacle, clearance)) {
          hitSegment = segmentIndex;
          break;
        }
      }
      if (hitSegment === -1) continue;
      const from = points[hitSegment].map(Math.round).join(', ');
      const to = points[hitSegment + 1].map(Math.round).join(', ');
      const relationId = relation.id ? ` id "${relation.id}"` : '';
      const message = `[clean-flow/edge-through-node] ${diagramType} ${relationCollection}[${relationIndex}]${relationId} "${relation.from}" -> "${relation.to}" crosses ${obstacleKind} "${obstacle.id}" (unrelated to this relationship) on segment ${hitSegment} [${from}] -> [${to}] (${clearance}px clearance) — ${routeHint}.`;
      recordDiagnostic({
        code: 'clean-flow/edge-through-node',
        severity: 'error',
        message,
        subject: relationshipSubject(diagramType, relationCollection, relationIndex, relation),
        evidence: {
          obstacleKind,
          obstacleId: obstacle.id,
          segmentIndex: hitSegment,
          from: points[hitSegment],
          to: points[hitSegment + 1],
          clearancePx: clearance,
        },
        supportedFixes: [routeHint],
      });
      problems.push(message);
    }
  }
  return problems;
}

// Reject only a proper interior X between relationships that share no semantic
// endpoint. Endpoint touches, branch/merge ports, and collinear shared
// corridors are intentionally outside this contract because geometry alone
// cannot tell whether those are authored junctions.
export function cleanCrossingProblems({
  relations,
  endpointIds,
  pathFor,
  diagramType,
  relationCollection,
  profile = 'standard',
  routeHint = 'adjust route/via or channel coordinates so the relationships use separate corridors'
}) {
  const requestedProfile = process.env.ARCHIFY_QUALITY_PROFILE || profile;
  const activeProfile = requestedProfile === 'showcase' ? 'showcase' : 'standard';
  if (activeProfile !== 'showcase') return [];
  const routed = asArray(relations).map((relation, index) => {
    if (!relation || !endpointIds.has(relation.from) || !endpointIds.has(relation.to)) return null;
    const points = pathFor(relation)?.points;
    if (!Array.isArray(points) || points.length < 2) return null;
    if (!points.every((point) => Array.isArray(point) && point.length === 2 && isFinitePoint(...point))) return null;
    return { relation, index, points };
  }).filter(Boolean);
  const problems = [];

  for (let leftIndex = 0; leftIndex < routed.length; leftIndex += 1) {
    const left = routed[leftIndex];
    for (let rightIndex = leftIndex + 1; rightIndex < routed.length; rightIndex += 1) {
      const right = routed[rightIndex];
      if ([left.relation.from, left.relation.to].some((id) => id === right.relation.from || id === right.relation.to)) continue;

      let hit = null;
      for (let leftSegment = 0; leftSegment < left.points.length - 1 && !hit; leftSegment += 1) {
        for (let rightSegment = 0; rightSegment < right.points.length - 1; rightSegment += 1) {
          const point = properSegmentIntersection(
            left.points[leftSegment],
            left.points[leftSegment + 1],
            right.points[rightSegment],
            right.points[rightSegment + 1]
          );
          if (point) {
            hit = { point, leftSegment, rightSegment };
            break;
          }
        }
      }
      if (!hit) continue;

      const describe = ({ relation, index }) => {
        const id = relation.id ? ` id "${relation.id}"` : '';
        return `${relationCollection}[${index}]${id} "${relation.from}" -> "${relation.to}"`;
      };
      const point = hit.point.map((value) => Math.round(value * 10) / 10).join(', ');
      const message = `[composition/proper-crossing] showcase ${diagramType} ${describe(left)} crosses ${describe(right)} at [${point}] (segments ${hit.leftSegment} and ${hit.rightSegment}) — ${routeHint}.`;
      recordDiagnostic({
        code: 'composition/proper-crossing',
        severity: 'error',
        message,
        subject: relationshipSubject(diagramType, relationCollection, left.index, left.relation),
        evidence: {
          otherRelationship: relationshipSubject(diagramType, relationCollection, right.index, right.relation),
          point: hit.point,
          segmentIndex: hit.leftSegment,
          otherSegmentIndex: hit.rightSegment,
        },
        supportedFixes: [routeHint],
      });
      problems.push(message);
    }
  }
  return problems;
}

// Two unrelated relationships that occupy the same visible corridor can read
// as one authored branch or merge even when neither relationship crosses a
// node or forms a proper X. Keep shared semantic endpoints exempt: their
// initial/final fan-out is real topology. Tiny overlaps below the route rhythm
// floor are ignored to avoid turning sub-pixel rounding into a quality debt.
export function collectAmbiguousCorridors({
  routedRelations,
  minOverlapPx = 8,
}) {
  const routed = asArray(routedRelations).map((entry, fallbackIndex) => {
    const relation = entry?.relation;
    if (!relation || typeof relation.from !== 'string' || typeof relation.to !== 'string') return null;
    const points = normalizeRoutePoints(entry?.points);
    if (points.length < 2) return null;
    return {
      relation,
      relationIndex: Number.isInteger(entry.relationIndex) ? entry.relationIndex : fallbackIndex,
      points,
    };
  }).filter(Boolean);
  const hits = [];

  for (let leftIndex = 0; leftIndex < routed.length; leftIndex += 1) {
    const left = routed[leftIndex];
    for (let rightIndex = leftIndex + 1; rightIndex < routed.length; rightIndex += 1) {
      const right = routed[rightIndex];
      if ([left.relation.from, left.relation.to].some((id) => id === right.relation.from || id === right.relation.to)) continue;

      let longest = null;
      for (let leftSegment = 0; leftSegment < left.points.length - 1; leftSegment += 1) {
        for (let rightSegment = 0; rightSegment < right.points.length - 1; rightSegment += 1) {
          const overlap = collinearAxisOverlap(
            left.points[leftSegment],
            left.points[leftSegment + 1],
            right.points[rightSegment],
            right.points[rightSegment + 1],
          );
          if (!overlap || overlap.length + 0.0001 < minOverlapPx) continue;
          if (!longest || overlap.length > longest.overlapLength + 0.0001) {
            longest = {
              left,
              right,
              leftSegment,
              rightSegment,
              overlapLength: overlap.length,
              overlapStart: overlap.start,
              overlapEnd: overlap.end,
            };
          }
        }
      }
      if (longest) hits.push(longest);
    }
  }
  return hits;
}

export function cleanAmbiguousCorridorProblems({
  relations,
  endpointIds,
  pathFor,
  diagramType,
  relationCollection,
  profile = 'standard',
  routeHint = 'adjust route/via or channel coordinates so the relationships use separate corridors',
  minOverlapPx = 8,
}) {
  const requestedProfile = process.env.ARCHIFY_QUALITY_PROFILE || profile;
  if (requestedProfile !== 'showcase') return [];
  const routedRelations = asArray(relations).map((relation, relationIndex) => {
    if (!relation || typeof relation.from !== 'string' || typeof relation.to !== 'string') return null;
    if (endpointIds && (!endpointIds.has(relation.from) || !endpointIds.has(relation.to))) return null;
    return { relation, relationIndex, points: pathFor(relation)?.points };
  }).filter(Boolean);

  return collectAmbiguousCorridors({ routedRelations, minOverlapPx }).map((hit) => {
    const describe = ({ relation, relationIndex }) => {
      const id = relation.id ? ` id "${relation.id}"` : '';
      return `${relationCollection}[${relationIndex}]${id} "${relation.from}" -> "${relation.to}"`;
    };
    const length = Math.round(hit.overlapLength * 10) / 10;
    const from = hit.overlapStart.map((value) => Math.round(value * 10) / 10).join(', ');
    const to = hit.overlapEnd.map((value) => Math.round(value * 10) / 10).join(', ');
    const message = `[composition/ambiguous-corridor] showcase ${diagramType} ${describe(hit.left)} shares a ${length}px corridor with ${describe(hit.right)} at [${from}] -> [${to}] (segments ${hit.leftSegment} and ${hit.rightSegment}; minimum ${minOverlapPx}px) — ${routeHint}.`;
    recordDiagnostic({
      code: 'composition/ambiguous-corridor',
      severity: 'error',
      message,
      subject: relationshipSubject(diagramType, relationCollection, hit.left.relationIndex, hit.left.relation),
      evidence: {
        otherRelationship: relationshipSubject(diagramType, relationCollection, hit.right.relationIndex, hit.right.relation),
        overlapLengthPx: length,
        minimumPx: minOverlapPx,
        from: hit.overlapStart,
        to: hit.overlapEnd,
        segmentIndex: hit.leftSegment,
        otherSegmentIndex: hit.rightSegment,
      },
      supportedFixes: [routeHint],
    });
    return message;
  });
}

// Relationship paths may cross a structural frame, but they must not borrow a
// frame side as a routing corridor. Rounded rectangle corners are trimmed from
// the modeled straight sides so a short corner touch is not mistaken for a
// border run. Any positive straight overlap beyond the numeric epsilon is a
// hard failure in every quality profile; 16px belongs only to the separate,
// neutral short-segment metric and is not a corridor exemption.
export function collectBorderRuns({ routedRelations, frames }) {
  const hits = [];
  for (const routed of asArray(routedRelations)) {
    const routeSegments = Array.isArray(routed?.segments)
      ? routed.segments
      : asArray(routed?.points).slice(0, -1).map((start, index) => ({ start, end: routed.points[index + 1] }));
    if (!routeSegments.length) continue;
    if (!routeSegments.every((segment) => (
      Array.isArray(segment?.start) && segment.start.length === 2 && isFinitePoint(...segment.start)
      && Array.isArray(segment?.end) && segment.end.length === 2 && isFinitePoint(...segment.end)
    ))) continue;
    for (const [frameIndex, frame] of asArray(frames).entries()) {
      for (const border of frameBorderSegments(frame)) {
        const overlaps = [];
        for (let segmentIndex = 0; segmentIndex < routeSegments.length; segmentIndex += 1) {
          const segment = routeSegments[segmentIndex];
          const overlap = collinearAxisOverlap(
            segment.start,
            segment.end,
            border.start,
            border.end,
          );
          if (!overlap || overlap.length <= 0.0001) continue;
          overlaps.push({ ...overlap, segmentIndex });
        }
        if (!overlaps.length) continue;
        const merged = mergeBorderOverlaps(overlaps, border);
        const longest = [...merged].sort((left, right) => right.length - left.length || left.low - right.low)[0];
        hits.push({
          ...routed,
          frame,
          frameIndex,
          side: border.side,
          segmentIndex: Math.min(...overlaps.map((overlap) => overlap.segmentIndex)),
          overlapLength: merged.reduce((total, overlap) => total + overlap.length, 0),
          overlapStart: longest.start,
          overlapEnd: longest.end,
        });
      }
    }
  }
  return hits;
}

export function cleanBorderRunProblems({
  relations,
  endpointIds,
  frames,
  pathFor,
  diagramType,
  relationCollection,
  profile,
  routeHint = 'adjust route/via or channel coordinates so the relationship crosses the frame perpendicularly through a clear opening'
}) {
  if (!process.env.ARCHIFY_QUALITY_PROFILE && !profile) return [];
  const routedRelations = asArray(relations).map((relation, relationIndex) => {
    if (!relation || typeof relation.from !== 'string' || typeof relation.to !== 'string') return null;
    if (endpointIds && (!endpointIds.has(relation.from) || !endpointIds.has(relation.to))) return null;
    return { relation, relationIndex, points: pathFor(relation)?.points };
  }).filter(Boolean);
  return collectBorderRuns({ routedRelations, frames }).map((hit) => {
    const relation = hit.relation || {};
    const relationId = relation.id ? ` id "${relation.id}"` : '';
    const frameKind = hit.frame?.kind || hit.frame?.shape || 'frame';
    const frameIdentity = hit.frame?.label || hit.frame?.id || hit.frameIndex;
    const length = Math.round(hit.overlapLength * 10) / 10;
    const from = hit.overlapStart.map((value) => Math.round(value * 10) / 10).join(', ');
    const to = hit.overlapEnd.map((value) => Math.round(value * 10) / 10).join(', ');
    const message = `[composition/container-border-run] ${diagramType} ${relationCollection}[${hit.relationIndex}]${relationId} "${relation.from}" -> "${relation.to}" follows ${frameKind} "${frameIdentity}" ${hit.side} border for ${length}px on segment ${hit.segmentIndex} [${from}] -> [${to}] — ${routeHint}.`;
    recordDiagnostic({
      code: 'composition/container-border-run',
      severity: 'error',
      message,
      subject: relationshipSubject(diagramType, relationCollection, hit.relationIndex, relation),
      evidence: {
        frameKind,
        frameId: hit.frame?.id,
        frameLabel: hit.frame?.label,
        side: hit.side,
        segmentIndex: hit.segmentIndex,
        overlapLengthPx: length,
        from: hit.overlapStart,
        to: hit.overlapEnd,
      },
      supportedFixes: [routeHint],
    });
    return message;
  });
}

export function routeBudgetMetrics({
  routedRelations,
  bendsPerRelationship = 2,
  stretch = 1.35,
  segmentPx = 16,
  microSegmentPx = 8,
}) {
  let maxBends = 0;
  let routesOverSuggestedBends = 0;
  let maxStretch = null;
  let routesOverSuggestedStretch = 0;
  let minSegmentPx = null;
  let minInteriorSegmentPx = null;
  let shortSegmentCount = 0;
  let shortEndpointSegmentCount = 0;
  let shortInteriorSegmentCount = 0;
  let microSegmentCount = 0;

  for (const routed of asArray(routedRelations)) {
    const points = normalizeRoutePoints(routed?.points);
    if (points.length < 2) continue;
    const bends = Math.max(0, points.length - 2);
    maxBends = Math.max(maxBends, bends);
    if (bends > bendsPerRelationship) routesOverSuggestedBends += 1;

    let routeLength = 0;
    for (let index = 0; index < points.length - 1; index += 1) {
      const length = Math.abs(points[index + 1][0] - points[index][0]) + Math.abs(points[index + 1][1] - points[index][1]);
      if (length <= 0.0001) continue;
      const position = segmentPosition(index, points.length - 1);
      routeLength += length;
      minSegmentPx = minSegmentPx == null ? length : Math.min(minSegmentPx, length);
      if (position === 'interior') {
        minInteriorSegmentPx = minInteriorSegmentPx == null ? length : Math.min(minInteriorSegmentPx, length);
      }
      if (length < segmentPx) {
        shortSegmentCount += 1;
        if (position === 'interior') shortInteriorSegmentCount += 1;
        else shortEndpointSegmentCount += 1;
      }
      if (length < microSegmentPx) microSegmentCount += 1;
    }
    const direct = Math.abs(points.at(-1)[0] - points[0][0]) + Math.abs(points.at(-1)[1] - points[0][1]);
    if (direct > 0.0001) {
      const routeStretch = routeLength / direct;
      maxStretch = maxStretch == null ? routeStretch : Math.max(maxStretch, routeStretch);
      if (routeStretch > stretch + 0.0001) routesOverSuggestedStretch += 1;
    }
  }

  return {
    maxBends,
    routesOverSuggestedBends,
    maxStretch,
    routesOverSuggestedStretch,
    minSegmentPx,
    minInteriorSegmentPx,
    shortSegmentCount,
    shortEndpointSegmentCount,
    shortInteriorSegmentCount,
    microSegmentCount,
  };
}

export function collectRouteRhythmIssues({
  routedRelations,
  interiorSegmentPx = 16,
  microSegmentPx = 8,
}) {
  const issues = [];
  for (const [fallbackIndex, routed] of asArray(routedRelations).entries()) {
    const points = normalizeRoutePoints(routed?.points);
    if (points.length < 2) continue;
    for (let segmentIndex = 0; segmentIndex < points.length - 1; segmentIndex += 1) {
      const start = points[segmentIndex];
      const end = points[segmentIndex + 1];
      const length = Math.abs(end[0] - start[0]) + Math.abs(end[1] - start[1]);
      if (length <= 0.0001) continue;
      const position = segmentPosition(segmentIndex, points.length - 1);
      const code = length < microSegmentPx - 0.0001
        ? 'composition/micro-segment'
        : position === 'interior' && length < interiorSegmentPx - 0.0001
          ? 'composition/short-interior-segment'
          : null;
      if (!code) continue;
      issues.push({
        code,
        relation: routed.relation,
        relationIndex: Number.isInteger(routed.relationIndex) ? routed.relationIndex : fallbackIndex,
        segmentIndex,
        position,
        length,
        start,
        end,
      });
    }
  }
  return issues;
}

export function cleanRouteRhythmProblems({
  relations,
  endpointIds,
  pathFor,
  diagramType,
  relationCollection,
  profile,
  routeHint = 'move the channel/via point to remove the cramped turn or give the route more corridor space',
  interiorSegmentPx = 16,
  microSegmentPx = 8,
}) {
  const requestedProfile = process.env.ARCHIFY_QUALITY_PROFILE || profile;
  if (requestedProfile !== 'showcase') return [];
  const routedRelations = asArray(relations).map((relation, relationIndex) => {
    if (!relation || typeof relation.from !== 'string' || typeof relation.to !== 'string') return null;
    if (endpointIds && (!endpointIds.has(relation.from) || !endpointIds.has(relation.to))) return null;
    return { relation, relationIndex, points: pathFor(relation)?.points };
  }).filter(Boolean);
  return collectRouteRhythmIssues({ routedRelations, interiorSegmentPx, microSegmentPx }).map((hit) => {
    const relation = hit.relation || {};
    const relationId = relation.id ? ` id "${relation.id}"` : '';
    const length = Math.round(hit.length * 10) / 10;
    const from = hit.start.map((value) => Math.round(value * 10) / 10).join(', ');
    const to = hit.end.map((value) => Math.round(value * 10) / 10).join(', ');
    const rule = hit.code === 'composition/micro-segment'
      ? `is below the ${microSegmentPx}px micro-segment floor`
      : `is below the ${interiorSegmentPx}px interior-segment floor`;
    const message = `[${hit.code}] showcase ${diagramType} ${relationCollection}[${hit.relationIndex}]${relationId} "${relation.from}" -> "${relation.to}" has a ${length}px ${hit.position} segment ${hit.segmentIndex} [${from}] -> [${to}] that ${rule} — ${routeHint}.`;
    recordDiagnostic({
      code: hit.code,
      severity: 'error',
      message,
      subject: relationshipSubject(diagramType, relationCollection, hit.relationIndex, relation),
      evidence: {
        segmentIndex: hit.segmentIndex,
        position: hit.position,
        lengthPx: length,
        minimumPx: hit.code === 'composition/micro-segment' ? microSegmentPx : interiorSegmentPx,
        from: hit.start,
        to: hit.end,
      },
      supportedFixes: [routeHint],
    });
    return message;
  });
}

export function cleanLabelRouteClearanceProblems({
  relations,
  labels,
  endpointIds,
  pathFor,
  diagramType,
  relationCollection,
  profile,
  threshold = 4,
  routeHint = 'adjust labelAt, labelDx, labelDy, or labelSegment; otherwise adjust the other relationship route/via/channel',
}) {
  const requestedProfile = process.env.ARCHIFY_QUALITY_PROFILE || profile;
  if (requestedProfile !== 'showcase') return [];
  const routedRelations = asArray(relations).map((relation, relationIndex) => {
    if (!relation || typeof relation.from !== 'string' || typeof relation.to !== 'string') return null;
    if (endpointIds && (!endpointIds.has(relation.from) || !endpointIds.has(relation.to))) return null;
    return { relation, relationIndex, points: pathFor(relation)?.points };
  }).filter(Boolean);
  return collectLabelRouteClearance({ labels, routedRelations, threshold }).map((hit) => {
    const describe = (relation, relationIndex) => {
      const relationId = relation?.id ? ` id "${relation.id}"` : '';
      const relationLabel = relation?.label ? ` label "${relation.label}"` : '';
      return `${relationCollection}[${relationIndex}]${relationId} "${relation?.from}" -> "${relation?.to}"${relationLabel}`;
    };
    const clearance = Math.round(hit.clearance * 10) / 10;
    const from = hit.start.map((value) => Math.round(value * 10) / 10).join(', ');
    const to = hit.end.map((value) => Math.round(value * 10) / 10).join(', ');
    const message = `[composition/label-route-clearance] showcase ${diagramType} label "${hit.label?.label || hit.labelRelation?.label || ''}" on ${describe(hit.labelRelation, hit.labelRelationIndex)} is ${clearance}px from ${describe(hit.otherRelation, hit.otherRelationIndex)} segment ${hit.segmentIndex} [${from}] -> [${to}] (label rect ${formatRect(hit.rect)}; minimum ${threshold}px) — ${routeHint}.`;
    recordDiagnostic({
      code: 'composition/label-route-clearance',
      severity: 'error',
      message,
      subject: relationshipSubject(diagramType, relationCollection, hit.labelRelationIndex, hit.labelRelation),
      evidence: {
        label: hit.label?.label || hit.labelRelation?.label || '',
        otherRelationship: relationshipSubject(diagramType, relationCollection, hit.otherRelationIndex, hit.otherRelation),
        segmentIndex: hit.segmentIndex,
        clearancePx: clearance,
        minimumPx: threshold,
        labelRect: hit.rect,
        from: hit.start,
        to: hit.end,
      },
      supportedFixes: [routeHint],
    });
    return message;
  });
}

function segmentPosition(index, segmentCount) {
  if (index === 0) return 'source-stub';
  if (index === segmentCount - 1) return 'target-stub';
  return 'interior';
}

function normalizeRoutePoints(points) {
  const finite = asArray(points).filter((point) => Array.isArray(point) && point.length === 2 && isFinitePoint(...point));
  const deduped = [];
  for (const point of finite) {
    const previous = deduped.at(-1);
    if (!previous || Math.abs(point[0] - previous[0]) > 0.0001 || Math.abs(point[1] - previous[1]) > 0.0001) deduped.push(point);
  }
  const normalized = [];
  for (const point of deduped) {
    while (normalized.length >= 2 && collinearForward(normalized.at(-2), normalized.at(-1), point)) normalized.pop();
    normalized.push(point);
  }
  return normalized;
}

function pointRectDistance(point, rect) {
  const dx = Math.max(rect.x - point[0], 0, point[0] - (rect.x + rect.width));
  const dy = Math.max(rect.y - point[1], 0, point[1] - (rect.y + rect.height));
  return Math.hypot(dx, dy);
}

function pointSegmentDistance(point, start, end) {
  const dx = end[0] - start[0];
  const dy = end[1] - start[1];
  const lengthSquared = dx * dx + dy * dy;
  if (lengthSquared <= 0.0000001) return Math.hypot(point[0] - start[0], point[1] - start[1]);
  const projection = Math.max(0, Math.min(1, ((point[0] - start[0]) * dx + (point[1] - start[1]) * dy) / lengthSquared));
  return Math.hypot(point[0] - (start[0] + projection * dx), point[1] - (start[1] + projection * dy));
}

function collinearForward(a, b, c) {
  if (Math.abs(crossProduct(a, b, c)) > 0.0001) return false;
  return (b[0] - a[0]) * (c[0] - b[0]) + (b[1] - a[1]) * (c[1] - b[1]) >= -0.0001;
}

function frameBorderSegments(frame) {
  if (!frame || typeof frame !== 'object') return [];
  if (frame.shape === 'line') {
    const start = frame.start || [frame.x1, frame.y1];
    const end = frame.end || [frame.x2, frame.y2];
    return isFinitePoint(...start, ...end) ? [{ side: 'line', start, end }] : [];
  }
  if (!isFinitePoint(frame.x, frame.y, frame.width, frame.height) || frame.width <= 0 || frame.height <= 0) return [];
  const radius = Math.max(0, Math.min(Number(frame.radius) || 0, frame.width / 2, frame.height / 2));
  const left = frame.x;
  const right = frame.x + frame.width;
  const top = frame.y;
  const bottom = frame.y + frame.height;
  return [
    { side: 'top', start: [left + radius, top], end: [right - radius, top] },
    { side: 'right', start: [right, top + radius], end: [right, bottom - radius] },
    { side: 'bottom', start: [right - radius, bottom], end: [left + radius, bottom] },
    { side: 'left', start: [left, bottom - radius], end: [left, top + radius] },
  ].filter(({ start, end }) => Math.hypot(end[0] - start[0], end[1] - start[1]) > 0.0001);
}

function mergeBorderOverlaps(overlaps, border) {
  const horizontal = Math.abs(border.start[1] - border.end[1]) <= 0.0001;
  const axis = horizontal ? 0 : 1;
  const fixed = horizontal ? border.start[1] : border.start[0];
  const sorted = overlaps.map((overlap) => ({
    low: Math.min(overlap.start[axis], overlap.end[axis]),
    high: Math.max(overlap.start[axis], overlap.end[axis]),
  })).sort((left, right) => left.low - right.low || left.high - right.high);
  const merged = [];
  for (const interval of sorted) {
    const previous = merged.at(-1);
    if (previous && interval.low <= previous.high + 0.0001) previous.high = Math.max(previous.high, interval.high);
    else merged.push({ ...interval });
  }
  return merged.map((interval) => ({
    ...interval,
    length: interval.high - interval.low,
    start: horizontal ? [interval.low, fixed] : [fixed, interval.low],
    end: horizontal ? [interval.high, fixed] : [fixed, interval.high],
  }));
}

function collinearAxisOverlap(a, b, c, d) {
  const epsilon = 0.0001;
  const horizontal = Math.abs(a[1] - b[1]) <= epsilon
    && Math.abs(c[1] - d[1]) <= epsilon
    && Math.abs(a[1] - c[1]) <= epsilon;
  const vertical = Math.abs(a[0] - b[0]) <= epsilon
    && Math.abs(c[0] - d[0]) <= epsilon
    && Math.abs(a[0] - c[0]) <= epsilon;
  if (!horizontal && !vertical) return null;
  const axis = horizontal ? 0 : 1;
  const low = Math.max(Math.min(a[axis], b[axis]), Math.min(c[axis], d[axis]));
  const high = Math.min(Math.max(a[axis], b[axis]), Math.max(c[axis], d[axis]));
  if (high - low <= epsilon) return null;
  const fixed = horizontal ? a[1] : a[0];
  return {
    length: high - low,
    start: horizontal ? [low, fixed] : [fixed, low],
    end: horizontal ? [high, fixed] : [fixed, high],
  };
}

function properSegmentIntersection(a, b, c, d) {
  const abC = crossProduct(a, b, c);
  const abD = crossProduct(a, b, d);
  const cdA = crossProduct(c, d, a);
  const cdB = crossProduct(c, d, b);
  const epsilon = 0.0001;
  const opposite = (left, right) => (left > epsilon && right < -epsilon) || (left < -epsilon && right > epsilon);
  if (!opposite(abC, abD) || !opposite(cdA, cdB)) return null;

  const denominator = (a[0] - b[0]) * (c[1] - d[1]) - (a[1] - b[1]) * (c[0] - d[0]);
  if (Math.abs(denominator) < epsilon) return null;
  const ab = a[0] * b[1] - a[1] * b[0];
  const cd = c[0] * d[1] - c[1] * d[0];
  return [
    (ab * (c[0] - d[0]) - (a[0] - b[0]) * cd) / denominator,
    (ab * (c[1] - d[1]) - (a[1] - b[1]) * cd) / denominator
  ];
}

function crossProduct(a, b, c) {
  return (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0]);
}

function pointInBox(point, box) {
  return point[0] >= box.x1 && point[0] <= box.x2 && point[1] >= box.y1 && point[1] <= box.y2;
}

function segmentsIntersect(a, b, c, d) {
  const o1 = orientation(a, b, c);
  const o2 = orientation(a, b, d);
  const o3 = orientation(c, d, a);
  const o4 = orientation(c, d, b);

  if (o1 === 0 && onSegment(a, c, b)) return true;
  if (o2 === 0 && onSegment(a, d, b)) return true;
  if (o3 === 0 && onSegment(c, a, d)) return true;
  if (o4 === 0 && onSegment(c, b, d)) return true;

  return o1 !== o2 && o3 !== o4;
}

function orientation(a, b, c) {
  const value = (b[1] - a[1]) * (c[0] - b[0]) - (b[0] - a[0]) * (c[1] - b[1]);
  if (Math.abs(value) < 0.0001) return 0;
  return value > 0 ? 1 : 2;
}

function onSegment(a, b, c) {
  return (
    b[0] <= Math.max(a[0], c[0]) &&
    b[0] >= Math.min(a[0], c[0]) &&
    b[1] <= Math.max(a[1], c[1]) &&
    b[1] >= Math.min(a[1], c[1])
  );
}

export function anchor(rect, side) {
  switch (side) {
    case 'left': return [rect.x, rect.cy];
    case 'right': return [rect.x + rect.width, rect.cy];
    case 'top': return [rect.cx, rect.y];
    case 'bottom': return [rect.cx, rect.y + rect.height];
    default:
      return [rect.x + rect.width, rect.cy];
  }
}

// Keep conservative auto-routed fan-out/fan-in relationships visually
// distinct without changing authored route controls. The returned map only
// contains endpoints that belong to a shared automatic midpoint anchor.
export function automaticPortSpread(relations, boxes, { gutter = 16, maxSpacing = 14 } = {}) {
  const groups = new Map();
  const spread = new Map();

  const add = (relation, endpoint, rect, side, counterpart) => {
    const key = `${rect.id}\u0000${side}`;
    const items = groups.get(key) || [];
    items.push({ relation, endpoint, rect, side, counterpart });
    groups.set(key, items);
  };

  for (const relation of asArray(relations)) {
    if (!relation || (relation.route && relation.route !== 'auto')) continue;
    if (relation.via || relation.channelX !== undefined || relation.channelY !== undefined || relation.labelAt) continue;
    const from = boxes.get(relation.from);
    const to = boxes.get(relation.to);
    if (!from || !to) continue;
    const fromSide = chosenSide(relation.fromSide, defaultFromSide(from, to));
    const toSide = chosenSide(relation.toSide, defaultToSide(from, to));
    add(relation, 'from', from, fromSide, to);
    add(relation, 'to', to, toSide, from);
  }

  for (const items of groups.values()) {
    if (items.length < 2) continue;
    const verticalSide = items[0].side === 'left' || items[0].side === 'right';
    items.sort((a, b) => {
      const aCoordinate = verticalSide ? a.counterpart.cy : a.counterpart.cx;
      const bCoordinate = verticalSide ? b.counterpart.cy : b.counterpart.cx;
      if (aCoordinate !== bCoordinate) return aCoordinate - bCoordinate;
      const aKey = `${a.relation.id || ''}\u0000${a.relation.from}\u0000${a.relation.to}\u0000${a.relation.label || ''}`;
      const bKey = `${b.relation.id || ''}\u0000${b.relation.from}\u0000${b.relation.to}\u0000${b.relation.label || ''}`;
      return aKey < bKey ? -1 : aKey > bKey ? 1 : 0;
    });

    const extent = verticalSide ? items[0].rect.height : items[0].rect.width;
    const usable = Math.max(0, extent - gutter * 2);
    const spacing = Math.min(maxSpacing, usable / (items.length - 1));
    if (!(spacing > 0)) continue;

    for (const [index, item] of items.entries()) {
      const offset = (index - (items.length - 1) / 2) * spacing;
      const point = anchor(item.rect, item.side);
      if (verticalSide) point[1] += offset;
      else point[0] += offset;
      const endpoints = spread.get(item.relation) || {};
      endpoints[item.endpoint] = point;
      spread.set(item.relation, endpoints);
    }
  }

  return spread;
}

export function defaultFromSide(from, to) {
  if (to.cx < from.cx) return 'left';
  if (to.cx > from.cx) return 'right';
  if (to.cy > from.cy) return 'bottom';
  return 'top';
}

export function defaultToSide(from, to) {
  if (to.cx < from.cx) return 'right';
  if (to.cx > from.cx) return 'left';
  if (to.cy > from.cy) return 'top';
  return 'bottom';
}

export function chosenSide(side, fallback) {
  return side && side !== 'auto' ? side : fallback;
}

export function polylinePath(points) {
  return points.map(([x, y], index) => `${index === 0 ? 'M' : 'L'} ${x} ${y}`).join(' ');
}

export function routePointsValue(points) {
  return asArray(points)
    .filter((point) => Array.isArray(point) && point.length === 2 && isFinitePoint(...point))
    .map(([x, y]) => `${x},${y}`)
    .join(';');
}

export function roundedPath(points, radius) {
  if (points.length < 3 || radius <= 0) {
    return polylinePath(points);
  }

  const commands = [`M ${points[0][0]} ${points[0][1]}`];
  for (let i = 1; i < points.length - 1; i += 1) {
    const [px, py] = points[i - 1];
    const [cx, cy] = points[i];
    const [nx, ny] = points[i + 1];
    const prevLen = Math.hypot(cx - px, cy - py);
    const nextLen = Math.hypot(nx - cx, ny - cy);
    const r = Math.min(radius, prevLen / 2, nextLen / 2);
    if (r < 1) {
      commands.push(`L ${cx} ${cy}`);
      continue;
    }
    const before = [cx - ((cx - px) / prevLen) * r, cy - ((cy - py) / prevLen) * r];
    const after = [cx + ((nx - cx) / nextLen) * r, cy + ((ny - cy) / nextLen) * r];
    commands.push(`L ${before[0]} ${before[1]}`);
    commands.push(`Q ${cx} ${cy} ${after[0]} ${after[1]}`);
  }
  const [endX, endY] = points[points.length - 1];
  commands.push(`L ${endX} ${endY}`);
  return commands.join(' ');
}

// Shared by edges/flows/transitions: all carry the same optional
// labelAt/labelDx/labelDy/labelSegment knobs.
export function labelPoint(item, points) {
  if (item.labelAt) return item.labelAt;
  if (points.length === 2) {
    return [
      (points[0][0] + points[1][0]) / 2 + (item.labelDx || 0),
      points[0][1] - 10 + (item.labelDy || 0)
    ];
  }
  const segmentIndex = Math.min(points.length - 2, Math.max(0, item.labelSegment ?? 1));
  const a = points[segmentIndex];
  const b = points[segmentIndex + 1];
  return [(a[0] + b[0]) / 2 + (item.labelDx || 0), (a[1] + b[1]) / 2 - 10 + (item.labelDy || 0)];
}

export const componentFill = {
  frontend: 'c-frontend',
  backend: 'c-backend',
  database: 'c-database',
  cloud: 'c-cloud',
  security: 'c-security',
  messagebus: 'c-messagebus',
  external: 'c-external'
};

export const componentText = {
  frontend: 't-frontend',
  backend: 't-backend',
  database: 't-database',
  cloud: 't-cloud',
  security: 't-security',
  messagebus: 't-messagebus',
  external: 't-external'
};

export const arrowClassMap = {
  default: ['a-default', 'arrowhead'],
  emphasis: ['a-emphasis', 'arrowhead-emphasis'],
  security: ['a-security', 'arrowhead-security'],
  dashed: ['a-dashed', 'arrowhead-dashed']
};

// Label accent per edge variant. Workflow colors dashed (async trace) labels
// like the trace store it points at; the other renderers use the bus color.
export function variantAccent(variant, { dashed = 't-messagebus' } = {}) {
  return variant === 'security'
    ? 't-security'
    : variant === 'emphasis'
      ? 't-backend'
      : variant === 'dashed'
        ? dashed
        : 't-muted';
}

export function formatRect(r) {
  return `[${Math.round(r.x)}, ${Math.round(r.y)}, ${Math.round(r.width)}, ${Math.round(r.height)}]`;
}

function formatDelta(n) {
  const v = Math.round(n);
  return v >= 0 ? `+${v}` : String(v);
}

/** Actionable hint when an edge label rect hits a node/component box (#7). */
export function suggestLabelObstacleFix(labelRect, lx, ly, obstacle, obstacleKind = 'component') {
  const lxR = Math.round(lx);
  const lyR = Math.round(ly);
  const belowY = Math.round(obstacle.y + obstacle.height + 14);
  const aboveY = Math.round(obstacle.y - 4);
  return [
    `  label rect: ${formatRect(labelRect)}`,
    `  ${obstacleKind} "${obstacle.id}" rect: ${formatRect(obstacle)}`,
    `  Suggested fix: labelAt [${lxR}, ${belowY}] or labelDy ${formatDelta(belowY - lyR)} (below); or labelAt [${lxR}, ${aboveY}] or labelDy ${formatDelta(aboveY - lyR)} (above)`,
  ].join('\n');
}

/** Hint when two edge labels collide. */
export function suggestLabelPairFix(a, b) {
  return [
    `  "${a.label}" ${formatRect(a)}; "${b.label}" ${formatRect(b)}`,
    '  Suggested fix: add labelDy +24 on one edge, adjust labelDx, or remove one label',
  ].join('\n');
}

/** Hint when two components/nodes are too close. */
export function suggestComponentSeparation(a, b, minGap = 8) {
  const rightX = Math.round(a.x + a.width + minGap);
  const belowY = Math.round(a.y + a.height + minGap);
  return [
    `  "${a.id}" ${formatRect(a)}; "${b.id}" ${formatRect(b)}`,
    `  Suggested fix: move "${b.id}" pos to [${rightX}, ${Math.round(b.y)}] (right of "${a.id}") or [${Math.round(b.x)}, ${belowY}] (below)`,
  ].join('\n');
}
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall