@ripple-ui/svelte 0.0.0-stage → 0.9.0-next.0

package/dist/widgets/c4/C4Diagram.svelte.d.ts

@@ -0,0 +1,36 @@
+import '@xyflow/svelte/dist/style.css';
+import type { C4Diagram as C4DiagramData, C4Status, C4Marker, C4Highlight, C4EdgeShape, C4Flow } from './types.js';
+interface Props {
+    diagram: C4DiagramData;
+    class?: string;
+    onclick?: (elementId: string) => void;
+    ondrilldown?: (elementId: string, level: string) => void;
+    /** Live state per element id. */
+    status?: Record<string, C4Status>;
+    /** Dots per element id (who is working there). */
+    markers?: Record<string, C4Marker[]>;
+    /** The element the camera frames while `follow` is true. */
+    focusId?: string;
+    follow?: boolean;
+    /** Controlled selection; leave undefined to let clicks select. */
+    selectedId?: string;
+    /** A user pan, zoom or zoom-button press moved the camera. */
+    onmanualcamera?: () => void;
+    /** Semantic zoom: ids drawn open on one canvas. Passing it (even []) turns the mode on. */
+    expanded?: string[];
+    /** Semantic zoom: the element being looked inside; everything outside it is ghosted. */
+    scopeId?: string;
+    /** Light this element's reach (in, out or both, to `depth`, default both and 3); dim the rest. */
+    highlight?: C4Highlight;
+    /** How edges draw along ELK's routes. Default 'orthogonal'. */
+    edgeShape?: C4EdgeShape;
+    /** A data flow to play over the map, one step at a time. */
+    flow?: C4Flow;
+    /** Controlled: the index of the flow's current step. Out of range, no step is shown. */
+    step?: number;
+    /** A connection was clicked: the index of the next step that travels it. */
+    onstep?: (n: number) => void;
+}
+declare const C4Diagram: import("svelte").Component<Props, {}, "">;
+type C4Diagram = ReturnType<typeof C4Diagram>;
+export default C4Diagram;

package/dist/widgets/c4/C4Edge.svelte

@@ -0,0 +1,145 @@
+<!--
+  C4Edge.svelte — the SvelteFlow edge for a C4 relationship that ELK routed: an orthogonal polyline
+  through ELK's points with rounded corners, the label at the box ELK reserved (beside the line,
+  clear of nodes). With `data.curved` it sweeps one cubic between the ports instead, label on its
+  midpoint, bending once through the route's midpoint where the sweep would cross a card in
+  `data.avoid` (curveEdge). C4Diagram only uses it when a route exists; otherwise edges stay smoothstep (a
+  bezier when curved).
+
+  `data.dim` (set while a highlight's reach leaves this edge out) dims its labels with it. A curved
+  edge in a bundle (`data.joinIn` / `joinOut`) runs to the join; the bundle's lead also draws the
+  trunk and the count, whose hover opens it (`c4-onjoin` context). Labels carry the edge's id and ends.
+
+  Semantic zoom adds two things through `data`: `items` (the relationships an aggregated edge
+  stands for), which turns the middle label into a hover target listing them, and `tail` / `head`
+  port badges where the edge meets an expanded boundary. A ghosted edge (both ends outside the
+  scope) dims its labels with it. Without them the edge renders as it always did.
+
+  A played flow step (`data.flow`, markFlow) swaps the label for a badge with the step's label and
+  runs a marker along this edge's own path (SVG animateMotion on the ripple curve, the other way for
+  a reply); under reduced motion the marker sits at the receiving end.
+-->
+<script lang="ts">
+  import { getContext } from 'svelte';
+  import { BaseEdge, EdgeLabel, type EdgeProps } from '@xyflow/svelte';
+  import C4PortBadge from './C4PortBadge.svelte';
+  import { curveEdge, roundedPath, EDGE_STROKE, MOVE_MS, RIPPLE_CURVE, type FlowMark, type Join } from './live.js';
+  import type { C4PortView } from './types.js';
+
+  type Point = { x: number; y: number };
+  type Box = Point & { width: number; height: number };
+  type Badge = { box: Box; text: string };
+
+  let { id, source, target, data, label, style, markerEnd, interactionWidth }: EdgeProps = $props();
+
+  const points = $derived((data?.points as Point[] | undefined) ?? []);
+  const box = $derived(data?.labelBox as Box | undefined);
+  const items = $derived(data?.items as C4PortView['items'] | undefined);
+  const tail = $derived(data?.tail as Badge | undefined);
+  const head = $derived(data?.head as Badge | undefined);
+  const ghost = $derived(!!data?.ghost);
+  const dim = $derived(data?.dim ? '' : undefined);
+  // A closed bundle's join stands in for this edge's end at the hub.
+  const shut = (j: unknown) => (j && !(j as Join).open ? (j as Join) : undefined);
+  const jin = $derived(shut(data?.joinIn));
+  const jout = $derived(shut(data?.joinOut));
+  const curve = $derived(
+    data?.curved
+      ? curveEdge(points, { labelBox: box, cards: (data.avoid as Box[] | undefined) ?? [], from: jout, to: jin })
+      : null
+  );
+  // The lead of each bundle draws its trunk and count (the count stays while open, so its hover can end).
+  const leads = $derived(
+    (['joinIn', 'joinOut'] as const).map((k) => data?.[k] as Join | undefined).filter((j): j is Join => !!j?.lead)
+  );
+  const onjoin = getContext<((key: string | null) => void) | undefined>('c4-onjoin') ?? (() => {});
+  const path = $derived(curve ? curve.d : roundedPath(points, 8));
+  // On the sweep, its midpoint; else ELK's label box, else the route's middle point.
+  const at = $derived(
+    curve?.at ?? (box ? { x: box.x + box.width / 2, y: box.y + box.height / 2 } : points[Math.floor(points.length / 2)])
+  );
+  // A label the layout wrapped (taller than one line, on a dense level) keeps its laid-out size.
+  const wrap = $derived(!!box && box.height > 20);
+  const centre = (b: Box) => ({ x: b.x + b.width / 2, y: b.y + b.height / 2 });
+  const mark = $derived(data?.flow as FlowMark | undefined);
+  // A reply's marker ends at the route's start; reach edges are never joined, so these are the path's ends.
+  const landing = $derived(mark?.back ? points[0] : points.at(-1));
+</script>
+
+<BaseEdge {id} {path} {style} markerEnd={jin ? undefined : markerEnd} {interactionWidth} />
+{#each leads as j (j.key)}
+  {#if !j.open}
+    {@const [a, b] = j.key.startsWith('in') ? [j.at, j.end] : [j.end, j.at]}
+    <path class="c4-trunk" d="M {a.x} {a.y} L {b.x} {b.y}" style:stroke={EDGE_STROKE} stroke-width="1.25" fill="none" marker-end={j.key.startsWith('in') ? markerEnd : undefined} />
+  {/if}
+  <EdgeLabel x={j.at.x} y={j.at.y} class="c4-badge-label">
+    <span class="c4-join-badge" role="note" aria-label="{j.count} connections" onpointerenter={() => onjoin(j.key)} onpointerleave={() => onjoin(null)}>{j.count}</span>
+  </EdgeLabel>
+{/each}
+
+{#if mark && at}
+  <EdgeLabel x={at.x} y={at.y} class="c4-badge-label" data-c4-flow-label>
+    <C4PortBadge port={mark.port} />
+  </EdgeLabel>
+  {#key mark.key}
+    {#if mark.still}
+      <circle class="c4-flow-marker" r="5" cx={landing?.x} cy={landing?.y} />
+    {:else}
+      <circle class="c4-flow-marker" r="5">
+        <!-- begin="indefinite" + beginElement: an animation inserted later with begin 0 has already ended. -->
+        <animateMotion
+          dur="{MOVE_MS}ms"
+          begin="indefinite"
+          fill="freeze"
+          {path}
+          calcMode="spline"
+          keyTimes="0;1"
+          keyPoints={mark.back ? '1;0' : '0;1'}
+          keySplines={RIPPLE_CURVE.join(' ')}
+          {@attach (el: SVGAnimationElement) => el.beginElement?.()}
+        />
+      </circle>
+    {/if}
+  {/key}
+{:else if label && at}
+  <EdgeLabel
+    x={at.x}
+    y={at.y}
+    selectEdgeOnClick={!items}
+    class={[ghost && 'c4-ghost-label', wrap && 'c4-wrap-label']}
+    data-c4-dim={dim}
+    data-c4-edge={id}
+    data-c4-ends="{source} {target}"
+    data-c4-reach={data?.reach ? '' : undefined}
+  >
+    {#if items}
+      <C4PortBadge port={{ text: String(label), items }} plain />
+    {:else}
+      {label}
+    {/if}
+  </EdgeLabel>
+{/if}
+
+{#each [tail, head] as badge, i (i)}
+  {#if badge && items}
+    <EdgeLabel
+      x={centre(badge.box).x}
+      y={centre(badge.box).y}
+      class={ghost ? 'c4-badge-label c4-ghost-label' : 'c4-badge-label'}
+      data-c4-dim={dim}
+    >
+      <C4PortBadge port={{ text: badge.text, items }} />
+    </EdgeLabel>
+  {/if}
+{/each}
+
+<style>
+  .c4-flow-marker {
+    /* Counter-scaled like the labels, so the marker stays visible on a far map. */
+    r: calc(5px / clamp(0.5, var(--c4-zoom, 1), 1));
+    fill: var(--ripple-accent);
+    stroke: var(--ripple-surface);
+    stroke-width: 2px;
+    pointer-events: none;
+  }
+</style>

package/dist/widgets/c4/C4Edge.svelte.d.ts

@@ -0,0 +1,4 @@
+import { type EdgeProps } from '@xyflow/svelte';
+declare const C4Edge: import("svelte").Component<EdgeProps, {}, "">;
+type C4Edge = ReturnType<typeof C4Edge>;
+export default C4Edge;

package/dist/widgets/c4/C4LiveLayer.svelte

@@ -0,0 +1,194 @@
+<!--
+  C4LiveLayer.svelte — the half of C4Diagram's live layer that needs the
+  SvelteFlow context, so it must render inside <SvelteFlow>. It moves the
+  camera (planCamera: refit on a new node set, follow the focus) and pins
+  marker dots to their nodes with NodeToolbar, which draws in screen space, so
+  a dot stays the same size at every zoom.
+
+  It also mirrors the zoom into --c4-zoom / data-c4-far / data-c4-near on the flow root, which
+  the node cards use to stay legible when zoomed out. Each write restyles the
+  whole map, so it writes only a change the cards can see, and holds still
+  while a camera move it started is flying.
+
+  The refit on a new node set is also what keeps the legacy drill-down fitted:
+  C4Diagram keeps SvelteFlow mounted across diagram swaps, so its `fitView`
+  prop only fires once.
+
+  A played flow step (`flowStep`: a key per step, its drawn element ids) frames those elements when
+  one is off screen (onScreen), on the ripple curve or as a cut under reduced motion; on screen, or
+  for the step already showing when the map first settles, the camera stays put.
+
+  Semantic zoom passes `frame` instead: a box from ELK's final layout and a
+  signature. The camera eases (the ripple curve, instant under reduced motion)
+  to that box whenever the signature changes, except when follow has just
+  turned off: a user who took the camera keeps it. Fitting ELK's box rather
+  than measured nodes means a node still growing on screen frames correctly.
+-->
+<script lang="ts">
+  import { safeStyle } from '@ripple-ui/core';
+  import {
+    NodeToolbar,
+    Position,
+    getViewportForBounds,
+    useNodesInitialized,
+    useStore,
+    useSvelteFlow,
+    useViewportInitialized,
+  } from '@xyflow/svelte';
+  import { untrack } from 'svelte';
+  import { prefersReducedMotion } from 'svelte/motion';
+  import { FIT_MIN_ZOOM, MOVE_MS, onScreen, planCamera, rippleEase, zoomVar, type CameraState, type Rect } from './live.js';
+  import type { C4Marker } from './types.js';
+
+  interface Props {
+    /** nodeSetKey of the rendered nodes. */
+    ids: string;
+    focusId?: string;
+    follow?: boolean;
+    markers?: Record<string, C4Marker[]>;
+    /** Semantic zoom's camera: frame `rect` when `key` changes. */
+    frame?: { key: string; rect: Rect | null; follow: boolean };
+    /** The current flow step: framed when its elements are off screen. */
+    flowStep?: { key: string; ids: string[] };
+  }
+
+  let { ids, focusId, follow, markers, frame, flowStep }: Props = $props();
+
+  /** Below this zoom the cards keep only name and technology (data-c4-far):
+   *  the 11px lines would read under 10px, and the counter-scaled name needs
+   *  their room inside the fixed ELK box. */
+  const FAR_ZOOM = 0.9;
+  /** From this zoom up a quiet (curved) map shows every edge label (data-c4-near). */
+  const NEAR_ZOOM = 1.2;
+
+  const flow = useSvelteFlow();
+  const store = useStore();
+  const initialized = useNodesInitialized();
+  const viewportReady = useViewportInitialized();
+
+  // DOM sync: the node cards read the zoom from CSS, so names counter-scale
+  // and stay legible when the map is zoomed out. --c4-zoom is inherited by
+  // every node, so each write restyles the whole map: write it only when the
+  // value the cards can see changes (zoomVar clamps to their range), and not
+  // while a camera move this layer started is flying (xyflow eases zoom out and
+  // back in, crossing many values); the move's final zoom is written on landing.
+  let written = '';
+  let flying = $state(false);
+  let flyTimer: ReturnType<typeof setTimeout> | undefined;
+  function fly(duration: number) {
+    clearTimeout(flyTimer);
+    flying = duration > 0;
+    // A timer, not the move's promise: xyflow never settles a move a newer one interrupts.
+    if (flying) flyTimer = setTimeout(() => (flying = false), duration + 40);
+  }
+  $effect(() => () => clearTimeout(flyTimer));
+  $effect(() => {
+    const el = store.domNode;
+    const zoom = store.viewport.zoom;
+    if (!el || flying) return;
+    const next = `${zoomVar(zoom)}|${zoom < FAR_ZOOM}|${zoom >= NEAR_ZOOM}`;
+    if (next === written) return;
+    written = next;
+    el.style.setProperty('--c4-zoom', zoomVar(zoom));
+    el.toggleAttribute('data-c4-far', zoom < FAR_ZOOM);
+    el.toggleAttribute('data-c4-near', zoom >= NEAR_ZOOM);
+  });
+  // The last camera input, kept outside reactivity: it is only compared.
+  let prev: CameraState | null = null;
+
+  // Escape hatch by design: this drives a third-party camera from props.
+  // It waits for SvelteFlow to measure the current nodes: a fit queued while a
+  // new level's nodes are still unadopted resolves against an empty set and
+  // parks the camera on the origin.
+  $effect(() => {
+    if (frame) return;
+    const next: CameraState = { ids, focusId, follow };
+    if (!initialized.current) return;
+    const move = planCamera(prev, next);
+    prev = next;
+    if (!move) return;
+    const duration = move.animate && !prefersReducedMotion.current ? 650 : 0;
+    fly(duration);
+    void flow.fitView(
+      move.nodeId
+        ? { nodes: [{ id: move.nodeId }], padding: 0.35, minZoom: FIT_MIN_ZOOM, maxZoom: 1, duration }
+        : { padding: 0.1, minZoom: FIT_MIN_ZOOM, maxZoom: 1, duration }
+    );
+  });
+
+  // Semantic camera (see the header).
+  let prevFrame: { key: string; follow: boolean } | null = null;
+  $effect(() => {
+    if (!frame || !viewportReady.current) return;
+    const { key, rect, follow: following } = frame;
+    const first = prevFrame === null;
+    const letGo = !!prevFrame?.follow && !following;
+    const same = prevFrame?.key === key;
+    prevFrame = { key, follow: following };
+    if (!rect || (!first && (letGo || same))) return;
+    const vp = getViewportForBounds(rect, store.width, store.height, FIT_MIN_ZOOM, 1, 0.08);
+    const duration = first || prefersReducedMotion.current ? 0 : MOVE_MS;
+    fly(duration);
+    void flow.setViewport(vp, { duration, ease: rippleEase });
+  });
+
+  // Flow step camera (see the header). null: not yet observed.
+  let seenStep: string | undefined | null = null;
+  $effect(() => {
+    const s = flowStep;
+    if (!initialized.current) return;
+    const first = seenStep === null;
+    if (!first && s?.key === seenStep) return;
+    seenStep = s?.key;
+    if (first || !s?.ids.length) return;
+    const visible = untrack(() => {
+      const boxes = s.ids.flatMap((id) => {
+        const n = flow.getInternalNode(id);
+        return n ? [{ ...n.internals.positionAbsolute, width: n.measured.width ?? 0, height: n.measured.height ?? 0 }] : [];
+      });
+      return onScreen(boxes, store.viewport, store.width, store.height);
+    });
+    if (visible) return;
+    const duration = prefersReducedMotion.current ? 0 : MOVE_MS;
+    fly(duration);
+    void flow.fitView({ nodes: s.ids.map((id) => ({ id })), padding: 0.35, minZoom: FIT_MIN_ZOOM, maxZoom: 1, duration, ease: rippleEase });
+  });
+
+  const onMap = $derived.by(() => {
+    if (!markers) return [];
+    const present = new Set(ids.split('\n'));
+    return Object.entries(markers).filter(([id, list]) => list.length > 0 && present.has(id));
+  });
+</script>
+
+{#each onMap as [nodeId, list] (nodeId)}
+  <NodeToolbar {nodeId} isVisible position={Position.Top} align="end" offset={-7}>
+    <span class="c4-markers" role="list" aria-label="Here now">
+      {#each list as m (m.id)}
+        <span
+          class="c4-marker"
+          role="listitem"
+          aria-label={m.label}
+          title={m.label}
+          style={safeStyle(`background: ${m.color}`)}
+        ></span>
+      {/each}
+    </span>
+  </NodeToolbar>
+{/each}
+
+<style>
+  .c4-markers {
+    display: flex;
+    gap: 3px;
+    padding-right: 12px;
+    pointer-events: auto;
+  }
+
+  .c4-marker {
+    width: 12px;
+    height: 12px;
+    border-radius: 50%;
+    box-shadow: 0 0 0 2px var(--ripple-popover);
+  }
+</style>

package/dist/widgets/c4/C4LiveLayer.svelte.d.ts

@@ -0,0 +1,23 @@
+import { type Rect } from './live.js';
+import type { C4Marker } from './types.js';
+interface Props {
+    /** nodeSetKey of the rendered nodes. */
+    ids: string;
+    focusId?: string;
+    follow?: boolean;
+    markers?: Record<string, C4Marker[]>;
+    /** Semantic zoom's camera: frame `rect` when `key` changes. */
+    frame?: {
+        key: string;
+        rect: Rect | null;
+        follow: boolean;
+    };
+    /** The current flow step: framed when its elements are off screen. */
+    flowStep?: {
+        key: string;
+        ids: string[];
+    };
+}
+declare const C4LiveLayer: import("svelte").Component<Props, {}, "">;
+type C4LiveLayer = ReturnType<typeof C4LiveLayer>;
+export default C4LiveLayer;

package/dist/widgets/c4/C4PortBadge.svelte

@@ -0,0 +1,85 @@
+<!--
+  C4PortBadge.svelte — one aggregated connection on the C4 map: a small pill ("→ Ripple · 2")
+  whose hover or keyboard focus lists the relationships behind it, through ripple's Tooltip. It
+  sits at an edge's end where the edge meets an expanded boundary (C4Edge), as a chip on the scope
+  boundary (C4GroupNode), and `plain` as the hover target of an aggregated edge's middle label.
+  `nopan nodrag` and the click guard keep a press on it from panning the map or picking the node.
+-->
+<script lang="ts">
+  import * as Tooltip from '../../components/ui/tooltip/index.js';
+  import type { C4PortView } from './types.js';
+
+  let { port, plain = false }: { port: C4PortView; plain?: boolean } = $props();
+</script>
+
+<Tooltip.Root delayDuration={120}>
+  <Tooltip.Trigger
+    class={plain ? 'c4-port c4-port-plain nopan nodrag' : 'c4-port nopan nodrag'}
+    onclick={(e: MouseEvent) => e.stopPropagation()}
+  >
+    {port.text}
+  </Tooltip.Trigger>
+  <Tooltip.Content side="top" sideOffset={6}>
+    <ul class="c4-port-list">
+      {#each port.items as it, i (i)}
+        <li>
+          <span>{it.from} → {it.to}</span>
+          {#if it.label}<span class="c4-port-list-label">{it.label}</span>{/if}
+        </li>
+      {/each}
+    </ul>
+  </Tooltip.Content>
+</Tooltip.Root>
+
+<style>
+  /* Global: the trigger is bits-ui's button and the list is portaled out of the canvas. */
+  :global(.c4-port) {
+    display: inline-flex;
+    align-items: center;
+    white-space: nowrap;
+    font: inherit;
+    font-size: calc(11px / clamp(0.6, var(--c4-zoom, 1), 1));
+    font-weight: 500;
+    line-height: 1.2;
+    padding: 2px 8px;
+    border-radius: 9999px;
+    border: 1px solid var(--ripple-border);
+    background: var(--c4-card, var(--ripple-surface));
+    color: var(--ripple-surface-foreground);
+    cursor: default;
+    transition: border-color 150ms var(--ripple-ease-out);
+  }
+
+  :global(.c4-port:hover),
+  :global(.c4-port:focus-visible) {
+    border-color: color-mix(in oklab, var(--ripple-accent) 60%, transparent);
+    outline: none;
+  }
+
+  :global(.c4-port.c4-port-plain) {
+    /* The edge label decides: one line, or wrapped where the layout wrapped it (C4Edge). */
+    white-space: inherit;
+    padding: 0;
+    border: none;
+    background: none;
+    color: inherit;
+    font-size: inherit;
+  }
+
+  :global(.c4-port-list) {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+    display: grid;
+    gap: 4px;
+  }
+
+  :global(.c4-port-list li) {
+    display: grid;
+    gap: 1px;
+  }
+
+  :global(.c4-port-list-label) {
+    opacity: 0.7;
+  }
+</style>

package/dist/widgets/c4/C4PortBadge.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { C4PortView } from './types.js';
+type $$ComponentProps = {
+    port: C4PortView;
+    plain?: boolean;
+};
+declare const C4PortBadge: import("svelte").Component<$$ComponentProps, {}, "">;
+type C4PortBadge = ReturnType<typeof C4PortBadge>;
+export default C4PortBadge;

package/dist/widgets/c4/activate.d.ts

@@ -0,0 +1,2 @@
+import type { C4NodeData } from './types.js';
+export declare function activateNode(type: string | undefined, data: C4NodeData): void;

package/dist/widgets/c4/activate.js

@@ -0,0 +1,26 @@
+// activate.ts — what activating a C4 node does. Every node component calls activateNode on click
+// and C4Diagram calls it on Enter or Space, so the keyboard and the pointer cannot disagree.
+//
+// By SvelteFlow node type: person, system, container and component cards drill when the element
+// is drillable and the host listens for drill-downs, and click otherwise; boundaries (group),
+// databases, queues and code panels only click. The level handed to ondrilldown is the one each
+// card has always passed: person and system step down from the diagram's level, a container
+// drills to components on a container diagram and to code elsewhere, a component to code.
+/** The level a drillable node of this type drills to; undefined for types that never drill. */
+function drillLevel(type, level) {
+    if (type === 'person' || type === 'system') {
+        return level === 'context' ? 'container' : level === 'container' ? 'component' : 'code';
+    }
+    if (type === 'container')
+        return level === 'container' ? 'component' : 'code';
+    if (type === 'component')
+        return 'code';
+    return undefined;
+}
+export function activateNode(type, data) {
+    const target = drillLevel(type, data.diagramLevel);
+    if (target && data.drillable && data.ondrilldown)
+        data.ondrilldown(data.element, target);
+    else
+        data.onclick?.(data.element);
+}

package/dist/widgets/c4/elk-layout.d.ts

@@ -0,0 +1,103 @@
+import { type ElkNode } from 'elkjs/lib/elk.bundled.js';
+import type { C4Diagram, C4Element, C4Relationship } from './types.js';
+import { type C4Tree, type LiftedEdge, type Visibility } from './semantic.js';
+import './elk-worker.js';
+export interface ElkLayoutOptions {
+    direction?: 'DOWN' | 'RIGHT' | 'UP' | 'LEFT';
+    nodeSpacing?: number;
+    layerSpacing?: number;
+}
+export interface LayoutPosition {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface EdgeRoute {
+    /** Absolute points: start on the source box, bends, end on the target box. */
+    points: {
+        x: number;
+        y: number;
+    }[];
+    /** Where ELK put the label (absolute, top-left), when the edge has one. */
+    label?: LayoutPosition;
+}
+/** The text an edge's label shows: its label, then [technology]. */
+export declare function edgeLabelText(r: C4Relationship): string;
+/** What runElk needs of a Worker; tests pass a fake. */
+export type ElkWorkerLike = Pick<Worker, 'postMessage' | 'addEventListener'>;
+/** Swap how the layout worker is made (null: main thread only) and drop the running one. For tests. */
+export declare function setElkWorkerFactory(factory: () => ElkWorkerLike | null): void;
+/** Lay out an ELK graph: in the worker when there is one, else on the main thread. */
+export declare function runElk(graph: ElkNode): Promise<ElkNode>;
+/** Wider than this (width / height) and than WIDE_PX, a level is laid out again by runReadable. */
+export declare const WIDE = 2.5;
+/** Narrower than this, a fit into a usual canvas stays above FIT_MIN_ZOOM, so the first layout stands. */
+export declare const WIDE_PX = 2000;
+/** The widest a middle label is laid out (and drawn) on a level laid out again. */
+export declare const LABEL_CAP = 180;
+/** `graph` with every layer capped at five nodes, compact placement and middle labels wrapped at LABEL_CAP. */
+export declare function readable(graph: ElkNode): ElkNode;
+/** runElk, then once more through `readable` when the result is wider than WIDE and WIDE_PX. */
+export declare function runReadable(graph: ElkNode): Promise<ElkNode>;
+/** Determine ELK node dimensions for a given C4 element */
+export declare function getNodeDimensions(el: C4Element): {
+    width: number;
+    height: number;
+};
+/**
+ * Compute ELK-based layout for a C4 diagram.
+ *
+ * Strategy:
+ * - For context/container views: systems with containers become ELK parent nodes,
+ *   their containers become ELK children — giving proper nested group boxes.
+ * - Relationships map to ELK edges.
+ * - Returns a flat Map<id, LayoutPosition> for all elements.
+ */
+export declare function computeElkLayout(diagram: C4Diagram, options?: ElkLayoutOptions): Promise<Map<string, LayoutPosition>>;
+/** computeElkLayout plus ELK's edge routes and label boxes (empty if ELK failed). */
+export declare function computeElkGraph(diagram: C4Diagram, options?: ElkLayoutOptions): Promise<{
+    positions: Map<string, LayoutPosition>;
+    routes: Map<number, EdgeRoute>;
+}>;
+/** A semantic edge's route: its middle label and the port badges at either end, all absolute. */
+export interface SemanticRoute {
+    points: {
+        x: number;
+        y: number;
+    }[];
+    label?: LayoutPosition;
+    /** Badge by `to` (ELK's head). */
+    head?: LayoutPosition;
+    /** Badge by `from` (ELK's tail). */
+    tail?: LayoutPosition;
+}
+/** Boundary label row height: ELK leaves it free above the children. */
+export declare const BOUNDARY_TOP = 48;
+/**
+ * Layout for semantic zoom: every drawn element, nested to any depth. A boundary is an ELK compound
+ * sized around its children (never smaller than `minBoundary`, so its label row fits); everything
+ * else is a leaf of `sizeOf`. Port badges are ELK end labels, so they sit beside the line right
+ * where it meets the boundary, with space reserved.
+ */
+export declare function computeSemanticLayout(tree: C4Tree, vis: Visibility, edges: readonly LiftedEdge[], sizeOf: (id: string) => {
+    width: number;
+    height: number;
+}, minBoundary: (id: string) => {
+    width: number;
+    height: number;
+}, options?: ElkLayoutOptions): Promise<{
+    positions: Map<string, LayoutPosition>;
+    routes: Map<string, SemanticRoute>;
+}>;
+/**
+ * Determine whether a given C4 element should render as a "group" node in SvelteFlow.
+ * A group node is a system that has children containers — it draws a dashed boundary box.
+ */
+export declare function isGroupNode(el: C4Element): boolean;
+/**
+ * Get the SvelteFlow node type string for a C4 element.
+ * An explicit `kind` wins; without one the shape is inferred from the fields
+ * present, exactly as before `kind` existed.
+ */
+export declare function getNodeType(el: C4Element): string;