# Visual Linker — AI Reference

`@macrulez/visual-linker-core` / `-vue` / `-nuxt` — a framework-agnostic
engine that draws auto-routed SVG connector lines between DOM blocks you
already control, with a Vue 3 adapter (component + directives + composable)
and a Nuxt module wrapping it. Version 0.4.3. Overlay mode (you position the blocks,
the engine draws the lines) is the only implemented mode — mouse-driven
connection creation and an auto-layout mode are NOT implemented yet (see
the package's own docs/TECH_SPEC.md).

This document is hand-written for AI agents and other tools that generate
code against this package: every signature, default, and behavior note
below is verified directly against the TypeScript source (not summarized
from prose docs), and prose is kept to the minimum needed to use the API
correctly. For human-readable narrative docs (why you'd reach for each
piece, worked examples), see the interactive site instead:

- Full docs (EN): https://npm.vuecraft.ru/en/packages/visual-linker/guide/overview
- Full docs (RU): https://npm.vuecraft.ru/packages/visual-linker/guide/overview
- GitHub: https://github.com/macrulezru/visual-linker
- npm: https://www.npmjs.com/package/@macrulez/visual-linker-core

Links below starting with "/" are relative to https://npm.vuecraft.ru.

---

## 1. Package map — what to import from where

| Package | Install | Peer deps | Provides |
|---|---|---|---|
| `@macrulez/visual-linker-core` | `npm install @macrulez/visual-linker-core` | none | `createVisualLinker()`, the themes (`lightTheme`/`darkTheme`/`defineTheme`) and the config helpers (`mergeConfig`/`patchConfig`) — the framework-agnostic engine (section 3). |
| `@macrulez/visual-linker-vue` | `npm install @macrulez/visual-linker-vue` | `vue: ^3.3.0` | `<VisualLinker>`, the `v-vl-block`/`v-vl-port` directives, `VisualLinkerPlugin`, `useVisualLinker()`, the shared-config API `useVisualLinkerConfig()` etc. (section 4), **plus `export * from '@macrulez/visual-linker-core'`** — the full core surface. |
| `@macrulez/visual-linker-nuxt` | `npm install @macrulez/visual-linker-nuxt` | `nuxt: ^3.9.0 \|\| ^4.0.0` | Nuxt module: auto-imports `<VisualLinker>`/`useVisualLinker` from `-vue`, registers `v-vl-block`/`v-vl-port` (server + client), installs the `visualLinker` key of `nuxt.config.ts` as the app-wide shared configuration (section 5). Depends on `-vue` internally. |

**Rule: install exactly one package and import everything from it** —
`-vue` re-exports 100% of `-core`, including the enums (`VLConnectionCurveEnum`
etc.) and every type. Installing `-core` alongside `-vue` is redundant,
never required. `-nuxt` doesn't need `-vue` installed separately either.

---

## 2. Core types (verbatim from `@macrulez/visual-linker-core`'s `types.ts`/`enums.ts`)

0.4.0 REPLACED the flat `VisualLinkerOptions` (and every `defaultXxx`) with ONE structured `VisualLinkerConfig`. There is no `VisualLinkerOptions` any more.

```ts
enum VLConnectionCurveEnum { BEZIER = 'bezier', STRAIGHT = 'straight', SMOOTHSTEP = 'smoothstep' }
enum VLMarkerShapeEnum { CIRCLE = 'circle', SQUARE = 'square', DIAMOND = 'diamond', ARROW = 'arrow' }
enum VLFixedSideEnum { TOP = 'top', RIGHT = 'right', BOTTOM = 'bottom', LEFT = 'left', AUTO = 'auto' }
enum VLOrientEnum { AUTO = 'auto', FIXED = 'fixed' }

type FixedSide = 'top' | 'right' | 'bottom' | 'left'                  // (0.4.1) plain strings; enum members are accepted too
type PortSide = FixedSide | 'auto'
type ConnectionCurve = 'bezier' | 'straight' | 'smoothstep'
type MarkerShape = 'circle' | 'square' | 'diamond' | 'arrow'
// Write `curve: 'straight'`, `shape: 'arrow'`, `side: ['left', 'right']` as plain strings — they type-check.
// `VLConnectionCurveEnum.STRAIGHT` etc. is also accepted and has the same value. (Before 0.4.1 only enum
// members type-checked in TypeScript; strings still worked at runtime.)

// ---- entities (descriptors) ----
interface PortDescriptor {
  id: string
  target?: string | HTMLElement          // CSS selector (resolved against block.el) or direct element. default: block's own el
  side?: PortSide | FixedSide[]          // default: config.ports.side, else 'auto'. FixedSide[] narrows auto's candidate sides
  offset?: number                         // 0..1 along the resolved side. default: config.ports.offset, else 0.5. Ignored if anchorBlockId/anchorEl set
  anchorBlockId?: string                  // draws the point on ANOTHER block's border, tracking target's real position projected onto it. Ignored if anchorEl set
  anchorEl?: HTMLElement                  // like anchorBlockId but a direct element. Wins over anchorBlockId if both set
  spread?: PortSpread                     // overrides the block's portSpread; false opts this port out
}
interface PortSpreadOptions { gap?: number /* 16 */; padding?: number /* 8 */ }
type PortSpread = boolean | PortSpreadOptions   // true = defaults, false = explicitly off (beats an inherited setting)

interface DragBoundsInset { top?: number; right?: number; bottom?: number; left?: number }  // px, unset edges default 0
type DragBounds = 'container' | HTMLElement | DragBoundsInset

interface BlockDescriptor {
  id: string
  el: HTMLElement
  ports?: PortDescriptor[]                // default: connections anchor to el's own border
  draggable?: boolean                     // overrides config.blocks.draggable for this block
  dragHandle?: string | HTMLElement       // default: whole block starts the drag
  dragBounds?: DragBounds                 // overrides config.blocks.drag.bounds for this block
  portSpread?: PortSpread                 // overrides config.ports.spread for every port side of this block; a port's own `spread` wins
  highlightable?: boolean                 // (0.4.3) overrides config.interaction.highlight for this block: hovering it highlights its connections
}

interface ConnectionEndpoint { blockId: string; portId?: string }  // portId unset → block's own border, side 'auto'
interface ConnectionDescriptor {
  id: string; from: ConnectionEndpoint; to: ConnectionEndpoint
  style?: ConnectionStyle                 // SAME SHAPE as config.lines, plus `markers`
  hoverable?: boolean                     // (0.4.3) overrides config.interaction.hover for this connection: the `hover` state + pointer cursor
  ariaLabel?: string                      // default 'Connection: {from block id} → {to block id}'
  labels?: ConnectionLabel[]              // omitted → Vue's single #connection-label slot at the midpoint
}
interface ConnectionLabel {
  id: string                              // unique within the connection
  position: 'start' | 'middle' | 'end' | number   // 'start'/'end' sit 24px in (at most half the line) from that end; number = fraction of length, 0..1
  offset?: number                         // px along the line's normal; POSITIVE = right of the direction of travel. default 0
  text?: string                           // set → drawn by the library (SVG pill); unset → only a position for your own content
  className?: string                      // on the library-drawn label's <g>; parts .vl-label-bg / .vl-label-text
  rotate?: boolean                        // follow the line, kept upright. default false
}

// ---- states ----
type VisualState = 'highlight' | 'hover' | 'selected' | 'focus'
type Stateful<T> = T & { highlight?: Partial<T>; hover?: Partial<T>; selected?: Partial<T>; focus?: Partial<T> }
// Layering, weakest → strongest: base < selected < highlight < hover < focus. `hover` = pointer over the connection's own line;
// `highlight` = pointer over one of its BLOCKS. With no `highlight` bucket (at any level) highlight behaves exactly like hover.
// Markers, ports and labels follow the state of THEIR connection. Blocks have no states.

// ---- the configuration ----
interface VisualLinkerConfig {
  theme?: Theme
  lines?: LinesConfig
  markers?: MarkersConfig
  ports?: PortsConfig
  labels?: LabelsConfig
  blocks?: BlocksConfig
  interaction?: InteractionConfig
}

interface LineStyle { color?: string /* '#2e8b57' */; width?: number /* 1.5 */; dashed?: boolean; opacity?: number /* 0..1 */ }
interface LineOptions {
  curve?: ConnectionCurve                 // default 'bezier'
  animated?: boolean | ConnectionFlow     // default off; false on a connection opts out of a group-level setting
  bezier?: { curvature?: number /* 0.5 */; minReach?: number /* 24 */; maxReach?: number /* 160 */; angleBlend?: number /* 0.55 */; angleMaxOffset?: number /* degrees, 30 */ }   // bezier only
  smoothstep?: { cornerRadius?: number /* 8 */; maxTrunkReach?: number /* 48; only for 2+ siblings sharing (block,port,side); smallest wins */ }  // smoothstep only
  routing?: { avoidObstacles?: boolean /* false */; padding?: number /* 12 */ }   // smoothstep only
  jumps?: boolean | { radius?: number /* 5 */ }   // smoothstep only; default off
}
type LinesConfig = Stateful<LineStyle> & LineOptions
type ConnectionStyle = LinesConfig & { markers?: { start?: MarkerInput; end?: MarkerInput } }

interface ConnectionFlow {
  speed?: number                          // px per SECOND. default 60
  direction?: 'forward' | 'backward'      // forward = from → to
  shape?: 'dashes' | 'dots'               // default 'dashes'
  dash?: number                           // ignored for dots. default 8
  gap?: number                            // default 14 (12 for dots)
  color?: string                          // unset = TINT mode: pattern in the line's own color, line dimmed to 0.35 (0.7 while emphasised). Set = this color over the unchanged line
  width?: number                          // default: line's width in tint mode; with an explicit color 60% of it (dots 120%, min 2.5px)
}

interface MarkerArrowConfig { color?: string /* follows the line color, NOT the shape's fill */; gap?: number /* 0 */ }
interface MarkerStyle {
  shape?: MarkerShape                     // default 'circle'. Ignored if svg is set
  size?: number                           // multiple of the current stroke width. default markers.sizes[shape] = 6 for EVERY shape
  color?: string                          // fill. default: the connection's line color IN THE CURRENT STATE (theme-aware). Ignored by 'arrow'
  strokeColor?: string                    // outline. default none. No effect on 'arrow'
  strokeWidth?: number                    // default 1. Ignored if strokeColor unset
  opacity?: number                        // default: the line's opacity (drawn inside <g opacity>, since markers don't inherit stroke-opacity)
  className?: string                      // CSS class on the marker's root <marker> element
  svg?: string                            // raw inner SVG markup, overrides shape, 0 0 20 20 viewBox — NOT sanitized
  orient?: 'auto' | 'fixed'               // default 'auto' for 'arrow', 'fixed' otherwise. FORCED to 'auto' when `arrow` is set
  arrow?: boolean | MarkerArrowConfig     // also an arrowhead right before the shape; tip lands on the shape's OUTER edge. Ignored when shape is 'arrow'
}
type MarkerConfig = Stateful<MarkerStyle>        // a state bucket can change shape, svg, size, colors, outline, arrow
type MarkerInput = false | MarkerShape | MarkerConfig   // false = no marker AND no built-in port dot at that end (a bare point)
interface MarkersConfig {
  start?: MarkerInput; end?: MarkerInput          // configured here → replaces the built-in port dot at that end of EVERY connection
  sizes?: { circle?: number; square?: number; diamond?: number; arrow?: number }   // each 6
}

interface PortStyle { radius?: number /* 4 */; fill?: string /* '#fff' */; stroke?: string /* follows the line color */; strokeWidth?: number /* 1.5 */; opacity?: number }
type PortsConfig = Stateful<PortStyle> & {
  show?: boolean                          // default true. The #port slot and the `layout` event work either way
  side?: PortSide | FixedSide[]           // default 'auto' — for ports that set none
  offset?: number                         // default 0.5 — for ports that set none
  spread?: PortSpread                     // default off
}
interface LabelStyle { background?: string; border?: string; color?: string; fontSize?: number /* 11 */; paddingX?: number /* 6 */; paddingY?: number /* 3 */; opacity?: number }
type LabelsConfig = Stateful<LabelStyle>          // library-drawn labels only (those with `text`)
interface BlocksConfig { draggable?: boolean /* false */; drag?: { grid?: number /* px, unset = free */; bounds?: DragBounds /* unset = unconstrained */ } }
interface InteractionConfig { hover?: boolean /* false (0.4.3) */; highlight?: boolean /* false (0.4.3) */; selectable?: boolean /* false */; clipToScrollParents?: boolean | 'pin' | 'hide' /* 'pin'; true = 'pin' */ }

interface Theme {   // color tokens → CSS variables written on the <svg>
  line?: string            // --vl-line-color            #2e8b57 (lightTheme)
  lineHover?: string       // --vl-line-color-active     #2e8b57   (hover AND highlight)
  lineSelected?: string    // --vl-line-color-selected   #2e8b57   (falls back to lineHover)
  selectedHalo?: string    // --vl-selected-color        #1f6feb
  focusRing?: string       // --vl-focus-color           #1f6feb
  portFill?: string        // --vl-port-fill             #ffffff
  portStroke?: string      // --vl-port-stroke-color     #2e8b57
  labelBackground?: string // --vl-label-bg              #ffffff
  labelBorder?: string     // --vl-label-border          #2e8b57
  labelText?: string       // --vl-label-color           #1c1e2b
}
const lightTheme: Theme; const darkTheme: Theme
function defineTheme(overrides: Theme, base: Theme = lightTheme): Theme    // a copy of base with overrides
function mergeConfig<T>(...layers: (T | undefined)[]): T      // deep merge; later wins; `undefined` values IGNORED; plain objects only (DOM elements/arrays are opaque)
function patchConfig<T>(base: T, patch: T): T                  // deep merge where `undefined` DELETES the key
function mergeMarkerInputs(base: MarkerInput | undefined, over: MarkerInput | undefined): MarkerConfig | false | undefined

// ---- outputs ----
interface ConnectionLayout {   // one per connection, fired on the 'layout' event — coordinates LOCAL to the container
  id: string; from: Point; to: Point; mid: Point; fromAngle: number; toAngle: number  // angles in degrees
  labels: LabelLayout[]                  // every ConnectionDescriptor.labels entry resolved onto the line (empty without `labels`)
  fromClipped?: boolean; toClipped?: boolean   // that end was pinned to a clipping ancestor's edge (the real port is out of view)
}
interface LabelLayout { id: string; point: Point; angle: number; rotation: number; text?: string; className?: string }  // point includes `offset`; rotation = upright(angle) if rotate else 0
interface PortLayout {   // one per resolved, DISTINCT physical point (deduped by rounded x/y, not by (blockId,portId)) that has no configured marker
  key: string; blockId: string; portId?: string; point: Point
}

interface VisualLinkerEventMap {
  'block:dragstart': { blockId: string }
  'block:drag': { blockId: string; x: number; y: number }
  'block:dragend': { blockId: string; x: number; y: number }
  'block:mouseenter': { blockId: string }        // always fires; puts the block's connections into the `highlight` state only with interaction.highlight / block.highlightable
  'block:mouseleave': { blockId: string }
  'connection:click': { connection: ConnectionDescriptor }
  'connection:mouseenter': { connection: ConnectionDescriptor }   // always fires; puts it into the `hover` state only with interaction.hover / connection.hoverable
  'connection:mouseleave': { connection: ConnectionDescriptor }
  'connection:selectionchange': { selectedIds: string[] }         // user input only — NOT fired by setSelectedConnections()
  'connection:delete-request': { connections: ConnectionDescriptor[] }  // Delete/Backspace: the selected ones, or just the focused one when it isn't selected. Nothing is removed
  layout: { connections: ConnectionLayout[]; ports: PortLayout[] }   // fired at the end of EVERY render pass
}
```

**Resolution order for any visual setting** (strongest first): the field on the entity (connection `style`, port, block, label) → the matching group of the engine's config → the shared config of the Vue app / Nuxt project (merged under the component's own `config`) → the theme token → a CSS variable of the app → the built-in value. Layers are merged FIELD BY FIELD and STATE BY STATE. A state bucket ranks above base fields at EVERY level: group `hover.color` beats a connection's own base `color` while hovered, unless the connection sets `hover.color` too.

---

## 3. `@macrulez/visual-linker-core`

### 3.1 `createVisualLinker(container, config?)`

```ts
function createVisualLinker(container: HTMLElement, config?: VisualLinkerConfig): VisualLinker

interface VisualLinker {
  setBlocks(blocks: BlockDescriptor[]): void              // full replace, triggers immediate render
  setConnections(connections: ConnectionDescriptor[]): void // full replace, triggers immediate render
  updateBlock(id: string, patch: Partial<Omit<BlockDescriptor, 'id'>>): void  // merge; no-op if id not registered; id itself cannot be changed via patch
  addConnection(connection: ConnectionDescriptor): void     // incremental add
  removeConnection(id: string): void                        // incremental remove
  setSelectedConnections(ids: readonly string[]): void      // replaces the selection (interaction.selectable only); ids not among the connections are dropped; emits NO event
  setConfig(patch: VisualLinkerConfig): void                // (0.4.0) deep-merge; a key patched to `undefined` is REMOVED; everything redraws, listeners (drag, selection) are re-attached/removed to match
  replaceConfig(next: VisualLinkerConfig): void             // (0.4.0) replaces the whole configuration
  getConfig(): VisualLinkerConfig                           // (0.4.0) a COPY of the configuration in effect
  refresh(): void                                            // forces immediate recompute, bypasses the rAF batch
  on<E>(event: E, handler: (payload) => void): () => void   // returns unsubscribe; no separate off() method
  destroy(): void
}
```

```ts
import { createVisualLinker } from '@macrulez/visual-linker-core'

const container = document.querySelector<HTMLElement>('#diagram')!
const linker = createVisualLinker(container, { lines: { curve: 'smoothstep' } })

linker.setBlocks([
  { id: 'a', el: document.querySelector<HTMLElement>('#block-a')! },
  { id: 'b', el: document.querySelector<HTMLElement>('#block-b')!, ports: [{ id: 'in', side: 'left' }] },
])
linker.setConnections([
  { id: 'a-b', from: { blockId: 'a' }, to: { blockId: 'b', portId: 'in' }, style: { markers: { end: 'arrow' } } },
])

const unsubscribe = linker.on('connection:click', ({ connection }) => console.log(connection.id))
// later: unsubscribe(); linker.destroy()
```

- **Auto-sets `container.style.position = 'relative'` if its computed
  `position` is `'static'`** (`svg-layer.ts`) — you do NOT have to set a
  positioning context yourself; the engine does it for you the first time
  it runs. Only relevant if `container`'s computed position is already
  something other than `static` (e.g. `absolute`/`fixed`) — those are left
  untouched.
- SVG layer: one `<svg class="vl-svg">` absolutely positioned (`inset: 0`,
  `pointer-events: none`) appended as the LAST child of `container`, with
  its own `<style>` and `<defs>` (markers) inside it. `<marker>` element
  ids are `vl-marker-<instanceId>-<counter>` — globally unique per page (a
  module-level counter), so multiple `VisualLinker` instances on the same
  page never collide on marker ids.
- Default look = CSS custom properties on the `<svg>`: `--vl-line-color`
  (`#2e8b57`), `--vl-line-width` (`1.5`), `--vl-line-color-active` (falls back to
  `--vl-line-color`), `--vl-line-color-selected` (falls back to `-active`),
  `--vl-selected-color`, `--vl-focus-color`, `--vl-port-fill`,
  `--vl-port-stroke-color`, `--vl-port-stroke-width`, `--vl-port-radius`,
  `--vl-label-bg/-border/-color`. The `theme` of the config writes exactly
  the theme tokens (section 2) onto the svg — a token the theme leaves out
  writes NOTHING (and an `undefined` token patched in later REMOVES its
  variable), so pure-CSS overrides keep working. Values from `lines`/`ports`/
  `labels` are set INLINE on the elements only when configured, so they beat
  CSS. MARKERS are JS-colored (the engine computes the line color of the
  moment from config + theme, it does not read CSS back).
- Each connection also gets an invisible, WIDER hit-area path
  (`.vl-connection-hit`, `stroke-width: 16`, `pointer-events: stroke`) laid
  under the visible line — `connection:click`/`mouseenter`/`mouseleave`
  fire off THIS element, not the thin visible stroke, so hover/click
  targeting is more forgiving than the drawn line width suggests.
- Resize/scroll: `container` and every block's `el` are watched via one
  shared `ResizeObserver`-driven watcher; its callbacks are coalesced into
  a single `requestAnimationFrame`-scheduled render (not one render per
  observed element). `window`'s own `scroll` (capture, passive) and
  `resize` (passive) listeners call the watcher's `scheduleNow()` directly
  — same rAF-coalesced scheduling, not a separate code path.
- `render()` (internal, runs every scheduled frame) does three passes:
  (1) resolve every connection's endpoints, (2) for `smoothstep`
  connections only, group siblings sharing `(blockId, portId, side)` on
  each end and compute a shared branch point, (3) build the actual SVG
  path strings and port markers. A connection whose `from`/`to` block
  isn't currently registered is silently skipped (not an error) — a
  `connection:*` event never fires for it either, since it's never added
  to `paths`.
- Emphasis (a connection `hover`ed, or `highlight`ed through an incident block, or selected): the
  emphasised paths are re-inserted just before the first `.vl-port` circle, so
  they paint ABOVE every other connection but still UNDER the port dots.
  Any NON-active connection whose start/end sits on the same physical
  point (`` `${blockId}:${Math.round(x)}:${Math.round(y)}` ``) as EITHER
  endpoint of any active connection hides its `marker-start`/`marker-end` there while the
  highlight lasts — only the marker, the line itself stays. Prevents a
  resting-size marker from overlapping the (possibly enlarged) active one.
- Ports rendered as `PortLayout` are deduplicated by **physical point**
  (`` `${blockId}:${Math.round(x)}:${Math.round(y)}` ``), not by
  `(blockId, portId)` — an `'auto'`-side port that resolves to a different
  point per connection gets one dot per distinct point, not one dot total.
- `updateBlock()`'s patch is applied by rebuilding the FULL internal block
  list and calling the same `setBlockList()` path `setBlocks()` uses — so
  every block's drag-interactivity listeners are torn down and
  re-attached on every `updateBlock()` call, not just the patched one
  (cheap, but worth knowing if you're calling it in a hot loop).
- Dragging: pointer-driven (`pointerdown`/`pointermove`/`pointerup`/
  `pointercancel`), uses `setPointerCapture` when available. The offset is
  written to the block's standalone CSS `translate` property
  (`el.style.translate = 'Xpx Ypx'`), NOT `transform` — it composes with any
  `transform` the block already has. Anything that rewrites the element's
  whole inline style (e.g. a Vue STRING `:style` binding changing) wipes
  the drag offset with it. `blocks.drag.bounds`
  is re-resolved to a live viewport-space rect on EVERY `pointermove` (not
  captured once at drag-start) — a `dragBounds` element (or the container
  itself) that resizes/moves mid-drag is respected with its current box,
  not a stale one from drag-start. `blocks.drag.grid` snaps the block's
  ABSOLUTE page position (not the raw per-frame pointer delta) to the
  grid, computed from a `basePosition` that already backs out any
  existing drag offset — so re-dragging an already-offset block still
  snaps correctly.

### 3.2 Behaviors (0.3.0 features; their config names are the 0.4.0 ones)

- **Selection (`interaction.selectable: true`, default off).** Every connection is a
  focusable button (Tab order = `connections` order): the invisible hit
  path gets `tabindex=0`, `role="button"`, `aria-pressed`; the focus ring is
  drawn on the VISIBLE line (`--vl-focus-color`, halo `--vl-selected-color`).
  Click / Enter / Space selects only that line; with Ctrl, Cmd or Shift it
  toggles within a multi-selection. Escape and a `pointerdown` outside the
  connection layer clear the selection; a connection that disappears
  leaves it. Delete/Backspace → `connection:delete-request` (the app removes
  — the library never mutates data). Without `interaction.selectable` the hit path is
  `aria-hidden` and the visible line is still `role="img"` + `aria-label`.
- **Labels.** Position = length along the sampled path (`path-sampling.ts`):
  bezier is flattened into 48 segments, smoothstep uses its polyline TO THE
  CORNERS (before rounding), same as `mid`. A label with `text` is an SVG
  pill sized by `getBBox` (a char-width estimate when it can't be measured).
  All labels live in one `<g class="vl-labels">` kept LAST in the `<svg>`, so
  lines are never drawn over them. No overlap avoidance between labels.
- **Animated flow.** One extra `<path class="vl-flow">` per animated
  connection, right behind its line; CSS `@keyframes` on `stroke-dashoffset`
  (`vl-flow-forward`/`vl-flow-backward`), speed in px/s. It follows its line
  when hover/selection raises it, uses the same `d` (hops included), has no
  pointer events, and is removed with the connection.
- **`lines.routing.avoidObstacles` (smoothstep only).** `routing.ts`: A* over a grid built
  from the obstacle edges (expanded by `routing.padding`) and the endpoints;
  state = node + direction, 24px penalty per turn, U-turns forbidden,
  straight 16px stubs along the port side's normal. A path that is already
  clear is returned BYTE-IDENTICAL to the old one (A* runs only for blocked
  routes). Obstacles = blocks within 240px of the connection's bounding box,
  minus the two end blocks, their DOM ancestors/descendants and blocks that
  contain an endpoint. If no path exists with full padding/stubs they shrink
  in steps; no path at all (or a grid over 6000 nodes) → the plain route is
  kept. Results are cached per inputs (`createRouteCache`). It replaces only
  the stretch between the branch-adjusted ends, so trunks/branches of
  sibling groups, corner rounding, labels and `layout` keep working. Obstacles
  beyond the 240px region are ignored.
- **`lines.jumps` (smoothstep only).** `jumps.ts`: horizontal segments of one
  connection against vertical segments of OTHER connections, on the
  unrounded polylines; the HORIZONTAL one hops (an arc `A r r 0 0 …`, bulging
  up), and only for a connection whose own `jumps` is on — but any line can be
  hopped over. Not counted: self-crossings, collinear overlaps (a shared
  trunk), T-junctions, crossings closer than `radius + smoothstep.cornerRadius + 1` to a
  segment end, a second arc closer than one arc's width. Output without
  `jumps` is byte-identical. `mid`, marker angles and labels are computed on
  the polyline WITHOUT arcs; the hit path and the flow overlay use the path
  with arcs. Needs all smoothstep polylines first, so obstacle routing runs
  before crossings are searched.
- **`interaction.clipToScrollParents`.** `clipping.ts`: the chain of ancestors with
  `overflow` other than `visible` is built from the PORT's element (not the
  block's — a row inside a scrolling block must clip) up to the container
  (excluded) and to `<body>`/`<html>`, cached per element until the block
  list changes. The visible rect = intersection of their rects on the axes
  they clip; a port outside it (1px tolerance) is clipped. `'pin'` clamps
  the point into the rect, drops that end's marker and port dot and sets
  `fromClipped`/`toClipped` on the layout; `'hide'` drops the connection.
- **Port spreading (`ports.spread` / `portSpread` / `spread`).** Connections sharing a `(block, port, side)` get
  virtual ports `gap` apart, centered on the port's point (shrinking the gap
  to fit inside the side minus `padding`), ordered by where each connection's
  OTHER end lies so lines don't cross; they re-order live while dragging.
  Works on horizontal and vertical sides. `false` at any level beats an
  inherited `true`.

### 3.3 State model and runtime changes (0.4.0)

- **How a look is resolved.** For a connection the engine builds a `view` =
  `mergeConfig(config.lines, connection.style)` (deep, state-by-state), then
  `fields = base ← selected ← highlight ← hover ← focus` for the states that
  are active. Width: a state `width` wins; otherwise an emphasised (hover /
  highlight / selected) line with an explicit base width gets `+1.5`. Markers:
  `mergeMarkerInputs(config.markers[end], style.markers[end])` then the same
  layering, with the line's color of the moment as the `color` fallback and the
  line's opacity as the `opacity` fallback. Ports/labels use the strongest state
  among the connections that own them. A marker/dot configured (even `false`)
  at an end REPLACES the built-in port dot there; `PortLayout` skips it.
- **Opacity.** `stroke-opacity` = line `opacity` × the tint dimming of an
  animated line (0.35, 0.7 when emphasised); the flow overlay gets the plain
  `opacity`. Markers get `<g opacity>`; ports `style.opacity`; labels `<g>` style.
- **Hover vs highlight.** `block:mouseenter` → `highlight` for the block's
  connections; a connection's own hit path `pointerenter` → `hover`. Both
  count as "emphasised" for width bump, painting order and hiding the markers
  of siblings that share an endpoint.
- **Both are OPT-IN (0.4.3).** `hover` needs `interaction.hover` (or
  `connection.hoverable`), `highlight` needs `interaction.highlight` (or
  `block.highlightable`); the local value wins over the global one. A
  `hover`/`highlight` bucket does nothing while its mode is off. The pointer
  cursor on a line appears only when hover is on for it OR the line is
  `selectable`. The engine events (`connection:mouseenter`/`mouseleave`/
  `click`, `block:mouseenter`/`mouseleave`) fire regardless; `selected` and
  `focus` do not depend on the flags. Both flags are read at paint/hover time,
  so `setConfig({ interaction: { hover: true } })` takes effect at once and
  switching it off ends a hover in progress.
- **`setConfig` / `replaceConfig`.** Re-resolve everything: theme variables are
  rewritten, port/label/line appearance recomputed, hit paths re-configured
  (`tabindex`/`role`/`aria-pressed` on or off with `interaction.selectable`),
  document listeners for selection attached/removed, block drag listeners
  rebuilt, then a full render. Turning `selectable` off clears the selection
  (emitting `connection:selectionchange`). `getConfig()` is a copy.

---

## 4. `@macrulez/visual-linker-vue` (own exports — also re-exports all of section 2–3)

### 4.1 `<VisualLinker>`

```ts
type RefFriendlyElement = string | MaybeRefOrGetter<HTMLElement | null | undefined>  // CSS selector string, OR a Vue ref/getter/plain element — NOT a selector wrapped in a ref
type RefFriendlyDragBounds = 'container' | RefFriendlyElement | DragBoundsInset

interface RefFriendlyPort extends Omit<PortDescriptor, 'target' | 'anchorEl'> {  // every other PortDescriptor field (id, side, offset, anchorBlockId) unchanged
  target?: RefFriendlyElement
  anchorEl?: MaybeRefOrGetter<HTMLElement | null | undefined>
}

interface VisualLinkerBlock {   // an entry of the OPTIONAL `blocks` prop
  id: string
  el?: RefFriendlyElement       // ref/getter/element, or a CSS selector (resolved inside the component's root, or across `document` with scope="page"). OMITTED → the entry only adds config to a block already marked in the template (v-vl-block/data-vl-block) with the same id; if no such block exists, the entry is dropped
  ports?: RefFriendlyPort[]
  draggable?: boolean
  highlightable?: boolean            // (0.4.3) overrides config.interaction.highlight for this block
  dragHandle?: RefFriendlyElement
  dragBounds?: RefFriendlyDragBounds
  portSpread?: PortSpread
}

type VisualLinkerScope = 'container' | 'page'

// Props:
//   connections: ConnectionDescriptor[]      — REQUIRED. watch(..., { deep: true })
//   blocks: VisualLinkerBlock[]              — default []. Optional: blocks are normally marked in the markup (4.4)
//   config: VisualLinkerConfig               — default {}. (0.4.0; was `options`.) REACTIVE: merged over the shared config, and a change calls engine.replaceConfig(...)
//   selected: string[]                       — (0.3.0) default undefined. Ids of selected connections (v-model:selected), needs config.interaction.selectable. Unset → the engine owns the selection. Watched deeply; applied AFTER setConnections so ids aren't pruned
//   scope: VisualLinkerScope                 — default 'container'
//   name: string                             — default undefined. Target for data-vl-linker / the directives' `linker` option
//   zIndex: number | string                  — default undefined. z-index of the drawing layer
//   inheritAttrs: false — any other attribute (class, style, id, …) is merged onto the ROOT div
// Emits (kebab-case, 1:1 with VisualLinkerEventMap, `block:x` → `block-x`, `connection:x` → `connection-x`):
//   block-dragstart, block-drag, block-dragend, block-mouseenter, block-mouseleave,
//   connection-click, connection-mouseenter, connection-mouseleave
//   (0.3.0) connection-selectionchange (string[] ids), connection-delete-request (ConnectionDescriptor[]), update:selected (string[])
// Slots:
//   default               — YOUR markup. Blocks/ports marked anywhere inside it (any depth, any wrapper components) are discovered
//   connection-label      — { connection, label?, point, angle?, rotation?, from, to } — only built if used. WITHOUT `connection.labels`: once, at the curve-aware midpoint (as before). WITH `labels` (0.3.0): once per label that has NO `text` (labels with text are drawn by the engine), at label.point rotated by `rotation`
//   port                  — { blockId, portId?, point } — only built if used
//   marker                — { connection, position: 'start'|'end', point, angle } — only rendered for an endpoint with NO marker configured (neither config.markers[pos] nor style.markers[pos]) and NOT for an end pinned to a scrolling container's edge (layout.fromClipped/toClipped)
// There are NO per-block slots and NO per-block wrapper elements.
```

```vue
<script setup lang="ts">
import { VisualLinker, vVlBlock, vVlPort } from '@macrulez/visual-linker-vue'

const connections = [
  { id: 'a-b', from: { blockId: 'a' }, to: { blockId: 'b', portId: 'in' }, style: { markers: { end: 'arrow' } } },
]
</script>

<template>
  <VisualLinker :connections="connections">
    <MyLayout>
      <MyCard v-vl-block="'a'" />
      <div v-vl-block="'b'" class="card">
        <span v-vl-port="{ id: 'in', side: 'left' }">input</span>
      </div>
    </MyLayout>
  </VisualLinker>
</template>
```

- Render tree: `<div class="vl-container" data-vl-root>` (attrs merged in; `position: relative` ONLY in container scope) containing the default slot and — in container scope — the drawing layer as its LAST child. The drawing layer is `<div class="vl-layer">` (`position: absolute; inset: 0; pointer-events: none; z-index: props.zIndex`); in page scope it's `<div class="vl-layer vl-layer--page">` with `position: fixed; inset: 0`, rendered through `<Teleport to="body">`, and the component returns a fragment `[root, Teleport]`.
- The engine is created on the LAYER element (`createVisualLinker(layerEl, mergeConfig(shared, props.config))`) — not on the root, and not on your markup. The SVG and the `.vl-overlay` div (holding whichever of the three overlay slots are used) both live inside the layer. Consequence: `blocks.drag.bounds: 'container'` means the component's own box in container scope, and the VIEWPORT in page scope.
- The layer is rendered only after `onMounted` (client only) — the SSR output contains the root and your slot content, but no layer; this keeps the server render and the hydration pass identical.
- Discovery (details in 4.4): a `MutationObserver` on the root (on `document.body` in page scope) watching `childList`, `subtree`, and the `data-vl-*` attributes (every `VL_ATTR` except `data-vl-root`) schedules a rescan; mutations inside `.vl-layer` are ignored. Directive mount/update/unmount also triggers a rescan of every live `<VisualLinker>`. A rescan runs inside a `watchEffect` (so refs read via `toValue()` — a `blocks` entry's `el`, a port's `target` — are tracked and re-sync once they resolve) and only calls `engine.setBlocks()` when the collected list is structurally different from the previous one.
- `engine.destroy()` is called automatically in `onBeforeUnmount` (observer disconnected, scope unregistered) — do not call it yourself from outside.
- Engine config: `mergeConfig(sharedConfig, props.config)` — recomputed on every change of either (the shared object is `reactive`), then `engine.replaceConfig()` — see 4.3.
- **SSR-safe**: no engine and no layer on the server. No `<ClientOnly>` wrapper needed anywhere, in plain Vue or in Nuxt (section 5).

### 4.2 `useVisualLinker(container, options?)`

```ts
interface UseVisualLinkerOptions {                  // (0.4.0) no longer extends the engine options
  config?: MaybeRefOrGetter<VisualLinkerConfig | undefined>   // ref, getter or plain object; merged over the shared config; watched → engine.replaceConfig()
  blocks?: MaybeRefOrGetter<RefFriendlyBlock[]>       // RefFriendlyBlock = BlockDescriptor with el/dragHandle/dragBounds/port.target/port.anchorEl all ref/getter-friendly
  connections?: MaybeRefOrGetter<ConnectionDescriptor[]>
}
interface UseVisualLinkerReturn { engine: ShallowRef<VisualLinker | null> }

function useVisualLinker(
  container: MaybeRefOrGetter<HTMLElement | null | undefined>,
  options?: UseVisualLinkerOptions,
): UseVisualLinkerReturn
```

- `engine.value` is `null` until `onMounted` AND `toValue(container)` resolves to a real element — check for `null` before calling engine methods synchronously after the composable call.
- If `options.blocks` is passed, it's synced via the SAME `watchEffect` pattern as the component (4.1) — omit it entirely to manage blocks yourself via `engine.value.setBlocks(...)`.
- If `options.connections` is passed, same `watch(..., { deep: true })` as the component. Omitting `blocks`/`connections` means NEITHER is ever auto-synced — the returned `engine` is otherwise a completely raw `VisualLinker` instance.
- `engine.value.destroy()` is called automatically in `onBeforeUnmount`.
- Same SSR-safe no-op behavior as the component (4.1) — engine creation happens only in `onMounted`.
- Must be called in `setup()` (it `inject`s the shared config).

### 4.3 Shared configuration (0.4.0) — `provide`/`inject`, NOT a global

REMOVED in 0.4.0: `visualLinkerDefaults`, `setVisualLinkerDefaults()`,
`resetVisualLinkerDefaults()`, the `VisualLinkerDefaults` type. Use:

```ts
app.use(VisualLinkerPlugin, { config?: VisualLinkerConfig })   // provides a reactive shared config to the app + registers <VisualLinker> and both directives
function useVisualLinkerConfig(): VisualLinkerConfig            // the reactive shared config in effect; THROWS ("no shared config…") if nothing provides one
function provideVisualLinkerConfig(initial?: VisualLinkerConfig): VisualLinkerConfig  // in setup(): provides a NEW reactive config to the subtree (REPLACES the app-level one, not merged) and returns it
function installVisualLinkerConfig(app: App, initial?: VisualLinkerConfig): VisualLinkerConfig  // same for a whole app (what the Nuxt plugin calls)
function createSharedConfig(initial?: VisualLinkerConfig): VisualLinkerConfig   // the reactive object, not provided
const VISUAL_LINKER_CONFIG_KEY: InjectionKey<VisualLinkerConfig>
```

```ts
const shared = useVisualLinkerConfig()
shared.theme = darkTheme                    // every diagram under the provider redraws
shared.lines = { ...shared.lines, curve: 'straight' }
delete shared.theme                          // removes the key
```

- Every `<VisualLinker>`/`useVisualLinker()` computes `mergeConfig(shared ?? undefined, ownConfig)` (own wins, field by field, state by state) inside a reactive getter, so a change to the shared object OR to the own config re-calls `engine.replaceConfig()`.
- No provider → components use only their own `config` (no error). State belongs to the app: nothing global, several Vue apps on a page are independent.

### 4.4 Marking blocks and ports: `v-vl-block` / `v-vl-port` / `data-vl-*`

```ts
interface BlockDirectiveOptions {
  id: string
  linker?: string                    // assigns the block to the <VisualLinker name="..."> with this name, wherever it sits
  draggable?: boolean
  highlightable?: boolean            // (0.4.3) overrides config.interaction.highlight for this block
  dragHandle?: RefFriendlyElement    // selector inside the block, or ref/getter/element
  dragBounds?: RefFriendlyDragBounds // a selector string here resolves against `document`
  portSpread?: PortSpread            // (0.3.0). A port directive takes `spread` (it is a PortDescriptor field)
}
type BlockDirectiveValue = string | BlockDirectiveOptions   // v-vl-block="'b1'" ≡ { id: 'b1' }

interface PortDirectiveOptions extends Omit<RefFriendlyPort, 'target'> {  // id, side, offset, anchorBlockId, anchorEl
  block?: string                     // owning block id. OMITTED → the nearest ancestor element registered as a block
  linker?: string
}
type PortDirectiveValue = string | PortDirectiveOptions     // v-vl-port="'out'" ≡ { id: 'out' }

const vVlBlock: ObjectDirective<HTMLElement, BlockDirectiveValue>
const vVlPort: ObjectDirective<HTMLElement, PortDirectiveValue>
const VL_ATTR: {
  root: 'data-vl-root', linker: 'data-vl-linker', block: 'data-vl-block', draggable: 'data-vl-draggable', highlightable: 'data-vl-highlightable',
  dragHandle: 'data-vl-drag-handle', dragBounds: 'data-vl-drag-bounds', port: 'data-vl-port',
  portBlock: 'data-vl-port-block', side: 'data-vl-side', offset: 'data-vl-offset', anchor: 'data-vl-anchor',
  portSpread: 'data-vl-port-spread', spread: 'data-vl-spread',   // (0.3.0)
}
```

- A directive-marked port's measured element (`target`) is ALWAYS the element carrying the directive — `target` is not an option.
- The directives mirror `data-vl-block`/`data-vl-port` (+ `data-vl-port-block`/`data-vl-linker` when set) onto the element; every other option lives off-DOM (a `WeakMap` keyed by the element), since it may hold refs/elements. `getSSRProps` emits those same attributes during server rendering.
- Plain attributes (no JS, e.g. server-rendered or third-party markup) — same registry:
  - `data-vl-block="id"` — block. `data-vl-draggable` — `""`/`"true"` → true, `"false"` → false (anything but the literal `"false"` is true). `data-vl-highlightable` — same values, for `highlightable`. `data-vl-drag-handle=".sel"` — selector inside the block. `data-vl-drag-bounds` — `"container"`, or a CSS selector resolved via `document.querySelector`.
  - `data-vl-port="id"` — port on the nearest ancestor block; `data-vl-port-block="id"` — or on this block explicitly. `data-vl-side` — one side (`top|right|bottom|left|auto`), or a space/comma-separated list → `FixedSide[]` (`auto` dropped from a list; unknown words ignored). `data-vl-offset` — number, non-finite/empty ignored. `data-vl-anchor="id"` → `anchorBlockId`.
  - `data-vl-port-spread` (block) / `data-vl-spread` (port) — (0.3.0) `""`/`"true"` → on with defaults, `"false"` → off, `"24"` → gap 24, `"24 4"` (or `"24,4"`) → gap 24 + padding 4.
  - `data-vl-linker="name"` — on a block or a port.
- Collection order for one scan: (1) every `[data-vl-block]` in scope that this instance owns; (2) `blocks` prop entries layered on top, per field; (3) every owned `[data-vl-port]`, appended to its owner's `ports` AFTER any `blocks`-prop ports. Precedence for the same block id: **`blocks` prop > directive options > data attributes**. For the same port id on one block, a `blocks`-prop port wins (the engine uses the first match).
- A port whose owner can't be found (no ancestor block, or `block`/`data-vl-port-block` naming an unknown id) is silently dropped.
- Ownership: an explicit `data-vl-linker` wins — it matches only the instance with that exact `name` (an element with `data-vl-linker` belongs to NO unnamed instance, not even its enclosing one); otherwise the nearest enclosing `[data-vl-root]` (so nested instances never take each other's blocks); otherwise (outside every `<VisualLinker>`) only page-scoped instances own it. Search root: the component's root element in container scope, `document` in page scope.
- Several page-scoped instances on one page all claim every unowned element — give each a `name` and assign elements explicitly.

### 4.5 `VisualLinkerPlugin`

```ts
const VisualLinkerPlugin: Plugin  // app.use(VisualLinkerPlugin) → app.component('VisualLinker'), app.directive('vl-block'), app.directive('vl-port')
```

Without the plugin, import `VisualLinker`, `vVlBlock`, `vVlPort` per component — in `<script setup>`, `vVlBlock`/`vVlPort` are usable as `v-vl-block`/`v-vl-port` automatically (Vue's `v`-prefix convention). Inside Nuxt the module registers the directives itself (section 5).

---

## 5. `@macrulez/visual-linker-nuxt`

Not an export surface — a Nuxt module (`configKey: 'visualLinker'`).

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@macrulez/visual-linker-nuxt'],
  visualLinker: {          // ModuleOptions = VisualLinkerConfig (0.4.0) — the SAME object createVisualLinker()/<VisualLinker :config> take
    theme: { line: '#6366f1', lineHover: '#312e81' },
    lines: { curve: 'smoothstep', width: 2, hover: { width: 3 }, jumps: true },
    markers: { end: { shape: 'arrow', hover: { size: 10 } } },
    ports: { radius: 5, spread: true },
    labels: { fontSize: 12 },
    blocks: { draggable: true, drag: { grid: 20, bounds: 'container' } },
    interaction: { selectable: true },
  },
})
```

- **Auto-imports/registers** (via `@nuxt/kit`): `<VisualLinker>` as a
  global component (`addComponent`), `useVisualLinker` as an auto-import
  (`addImports`) — both sourced from `@macrulez/visual-linker-vue`
  (so its full core re-export is reachable too, but core-level exports
  and `useVisualLinkerConfig` are NOT separately auto-imported by this
  module — import them from `@macrulez/visual-linker-vue`).
- **ONE universal plugin** (`runtime/plugin.ts`, server + client; the
  0.3 client-only plugin is gone): registers `v-vl-block`/`v-vl-port`
  (`nuxtApp.vueApp.directive(...)`, so their `getSSRProps` puts the
  `data-vl-*` attributes into the server-rendered HTML) AND calls
  `installVisualLinkerConfig(nuxtApp.vueApp, useRuntimeConfig().public.visualLinker)` —
  the shared config of section 4.3, which `useVisualLinkerConfig()` returns.
- The module copies the options as JSON into
  `runtimeConfig.public.visualLinker`, so they MUST be JSON-serializable:
  `blocks.drag.bounds` can be `'container'` or an inset object, never an
  `HTMLElement` (give an element to one diagram through its own `config` or
  a block).
- No `defaults` object passed to `defineNuxtModule()` — deliberate, so a
  field left unset stays unset all the way down to core's built-in values;
  a hardcoded default anywhere would silently shadow a future change to
  core's own default.
- `<VisualLinker>`/`useVisualLinker` are SSR-safe no-ops on their own
  (engine only created in `onMounted`). No `<ClientOnly>` wrapper is needed.

---

## 6. Consolidated gotcha list

Cross-cutting facts most likely to produce subtly wrong generated code if
missed — each is explained in full where it first applies above, listed
here for a fast pre-flight check:

1. **0.4.0 REPLACED every flat option with `VisualLinkerConfig`.** There is
   no `VisualLinkerOptions`, no `defaultCurve`/`showPorts`/`defaultPort*`/
   `default*MarkerSize`/`dragGridSize`/…, no `style.startMarker`/`endMarker`/
   `hoverStyle`/`selectedStyle`/`curvature`/`cornerRadius`/…, no Vue `options`
   prop, no `setVisualLinkerDefaults`. Generating any of those is a bug:
   use `lines`/`markers`/`ports`/`labels`/`blocks`/`interaction`/`theme`
   and `style.markers.{start,end}`/`style.hover`/`style.selected`/`style.bezier`/
   `style.smoothstep`/`style.routing` (section 2).
2. **`container` does NOT need `position: relative` set by hand** — the
   engine sets it automatically the first time it runs, if the computed
   position is `static` (3.1).
3. **`updateBlock()` cannot change a block's `id`** — its `patch` type is
   `Partial<Omit<BlockDescriptor, 'id'>>`. To change identity, remove and
   re-add via `setBlocks()`.
4. **`on()` has no matching `off()`** — the handler passed to `on()`
   returns its own unsubscribe function; call that instead.
5. **A connection referencing an unregistered block is silently
   skipped**, not an error and not an emitted event — if a connection
   "does nothing," check that both `from.blockId`/`to.blockId` are
   actually present in the current `setBlocks()` call.
6. **`smoothstep.maxTrunkReach`/the branch-point part of `cornerRadius`
   only apply when 2+ `smoothstep` connections share the exact same
   `(blockId, portId, side)`** — a solo `smoothstep` connection still gets
   rounded 90° bends, but never a "branch point".
7. **`offset` on a `PortDescriptor` is silently ignored whenever
   `anchorBlockId`/`anchorEl` is also set.**
8. **`markers.start/end: false` is not the same as leaving it unset** —
   `false` suppresses even the built-in port dot (a bare point for a Vue
   `#marker` slot); unset still shows the dot when `ports.show` is on. ANY
   marker configured at an end — on the connection OR in `config.markers`
   — replaces the dot there.
9. **Only `useVisualLinker` is auto-imported by the Nuxt module** — core
   functions/enums, `useVisualLinkerConfig` and the theme helpers must be
   imported from `@macrulez/visual-linker-vue` (or `-core`).
10. **`<VisualLinker>` has NO per-block slots and renders NO wrapper per
    block.** Mark block elements with `v-vl-block="id"` / `data-vl-block="id"`
    (4.4). The `blocks` prop is optional — an entry without `el` only adds
    config to a block marked in the template, and is dropped if none exists.
11. **In a template, `v-vl-block` needs a JS expression** — `v-vl-block="'a'"`
    or `v-vl-block="b.id"`, not `v-vl-block="a"`. The attribute form takes a
    literal: `data-vl-block="a"`.
12. **An element with `data-vl-linker`/`linker` belongs ONLY to the
    `<VisualLinker>` whose `name` matches.** An element outside every
    `<VisualLinker>` is owned only by `scope="page"` instances (4.4).
13. **`blocks.drag.bounds: 'container'` means the drawing layer's box** — the
    component's own box in container scope, the VIEWPORT with `scope="page"`.
14. **Drag writes `style.translate`, not `style.transform`.** A Vue STRING
    `:style` binding on a draggable block wipes the drag offset whenever
    that string changes — use an object `:style` or a class.
15. **The Vue `config` prop IS reactive in 0.4.0** (it was read once as
    `options` before): a change calls `engine.replaceConfig()`. Mutating a
    non-reactive object in place is not seen — replace the object, or pass a
    reactive one/ref. `connections` is deep-watched too.
16. **`marker.arrow` forces `orient: 'auto'`**, is ignored for `shape: 'arrow'`,
    and its color defaults to the LINE color, not the shape's fill. For a custom
    `svg` marker, `arrow.gap` is measured from the endpoint.
17. **While a connection is emphasised (`hover`/`highlight`/selected),
    sibling connections sharing one of its endpoints hide their marker at
    that point** (3.1) — expected behavior, not a rendering bug.
18. **`interaction.selectable` is OFF by default.** `setSelectedConnections()`
    and the Vue `selected` prop never fire `connection:selectionchange`; the
    library never deletes anything — `connection:delete-request` is only a
    request (3.2). Turning it off at runtime clears the selection.
19. **`lines.routing.avoidObstacles` and `lines.jumps` only affect
    `curve: 'smoothstep'`** — bezier/straight lines ignore both.
20. **A `labels` entry with `text` is drawn by the engine; without `text` it
    is only a position** — the Vue `#connection-label` slot is called ONLY for
    the latter, once per label. Positive `offset` is to the RIGHT of the
    direction of travel. Labels are not kept from overlapping each other. The
    look of library-drawn labels is `config.labels`.
21. **`interaction.clipToScrollParents` defaults to `'pin'`.** A port scrolled
    out of a clipping ancestor pins its line to the visible edge and drops
    that end's marker and port dot (and the Vue `#marker` slot). `false`
    restores always-drawn.
22. **`lines.animated` is inherited**; a connection opts out with
    `style.animated: false`. Without an explicit `color` the pattern is drawn
    in the line's own color and the line beneath it is dimmed (tint mode).
23. **Port spreading priority: `port.spread` > `block.portSpread` >
    `config.ports.spread`**; `false` at any level switches an inherited
    setting off. In Vue: `portSpread` on `v-vl-block`/`blocks` entries,
    `spread` on `v-vl-port`, or `data-vl-port-spread` / `data-vl-spread`.
24. **States: `hover` ≠ `highlight`.** A hovered BLOCK sets `highlight` on its
    connections; the pointer on a LINE sets `hover`. With no `highlight`
    bucket anywhere, highlight looks like hover. A state bucket beats base
    fields at every level (a group `hover.color` beats a connection's own
    `color` on hover) — set the connection's `hover.color` to keep its own.
25. **Marker color = the line's color of the current state** unless the marker
    sets `color`; theme tokens count. Marker `size` is a multiple of the
    stroke width, so it grows with a thicker line; a state's `size` overrides.
    Marker opacity follows the line's unless set. Stylesheet-only colors do
    NOT reach markers — put the color in `theme` too.
26. **Shared Vue config is `provide`/`inject`, not global.** `useVisualLinkerConfig()`
    THROWS without a provider (install `VisualLinkerPlugin` or call
    `provideVisualLinkerConfig()` in an ancestor). `provideVisualLinkerConfig`
    REPLACES the app-level config for its subtree (no merge). Change the shared
    object by assignment (`shared.theme = darkTheme`); `delete shared.key` removes.
27. **Nuxt options must be JSON** (they travel via `runtimeConfig.public`):
    no `HTMLElement` for `blocks.drag.bounds`. Nuxt auto-imports nothing but
    `<VisualLinker>` and `useVisualLinker`.
28. **`setConfig` deep-merges and `undefined` DELETES a key; `mergeConfig`
    (used for layering) IGNORES `undefined`.** Don't confuse them: to clear a
    runtime setting use `setConfig({ x: { y: undefined } })` or `replaceConfig`.
29. **A draggable block takes every pointer press on its whole area** (the engine
    calls `preventDefault` and captures the pointer to start the drag), so a
    button or input inside it never gets its click. Set `dragHandle` to a
    sub-element (`'.node-body'`) and keep interactive controls outside it.
30. **A selectable line's invisible hit area extends over the block where it
    ends** and takes clicks there. Do not put clickable controls (pins, buttons)
    on a block's edge at a line end; keep them away from the edge.
31. **Anchored ports (`anchorBlockId`/`anchorEl`): the point is drawn on the
    anchor's border, but "clipped?" is decided by the port's OWN element** (its
    center must be inside the visible area of its clipping ancestors). A visible
    row keeps its point on the anchor border even when that border is outside a
    clipping wrapper (e.g. a rounded `overflow: hidden` segmented control inside a
    padded block); a row scrolled out of view is pinned (marker and port dot
    dropped, `fromClipped`/`toClipped`). Ports WITHOUT an anchor are still tested
    by their point. (Before 0.4.2 the test used the anchored point, which pinned
    such rows to the wrapper's edge.)
32. **`block:dragend` `{ x, y }` is the offset from the block's BASE position**
    (its own left/top/layout), not an absolute position. To persist a layout store
    base + offset and use it as the new base on the next load; the engine then
    starts again from offset 0.
33. **`shared.theme = theme` replaces the whole theme object**, including tokens
    set earlier (e.g. in `nuxt.config.ts`); to change one token assign
    `{ ...shared.theme, line: '#…' }`. The label border is its own token
    (`labelBorder`) and does not follow `line`.
34. **SSR (Nuxt): read `localStorage`/`matchMedia` in `onMounted`**, keep the
    choice in `useState`. `useVisualLinkerConfig`, `lightTheme`, `darkTheme`,
    `defineTheme` are NOT auto-imported: import them from
    `@macrulez/visual-linker-vue` (a direct dependency of the project).
36. **`hover` and `highlight` are OFF by default (0.4.3).** A diagram does not
    react to the pointer and shows no pointer cursor until you set
    `interaction: { hover: true, highlight: true }` (or `connection.hoverable` /
    `block.highlightable` per entity; the local value wins). `hover`/`highlight`
    buckets in `lines`/`markers`/`ports`/`labels` are ignored while the mode is
    off, so a style that "does nothing on hover" usually just needs the flag.
    Events still fire. The default `+1.5` width bump comes with the state, so to
    keep a line still while hover is on, give the bucket the base width
    (`hover: { width: <lines.width> }`) or set `hoverable: false`.

## 7. Recipes (full verified code on the docs site, plain JS + Vue + Nuxt)

Pages under `/packages/visual-linker/guide/`:

- `recipes-er-diagram` — tables as blocks, columns as ports (`target` per row,
  `side: ['left','right']`), `ports.spread`, `N`/`1` labels, `highlight` (needs
  `interaction.highlight`), drag by `dragHandle`.
- `recipes-flow-editor` — draggable nodes, `smoothstep` + `routing.avoidObstacles`
  + `jumps`, `animated`, click-to-connect via your own handlers, `selectable` +
  `connection:delete-request` (the app owns the list and removes the line).
- `recipes-field-mapping` — two scrolling lists, row ports, `clipToScrollParents:
  'pin'` (or `'hide'`).
- `recipes-editable-diagram` — add/remove nodes, persist positions from
  `block:dragend` (base + offset), SSR-safe restore in `onMounted`.
- `recipes-themes` — `lightTheme`/`darkTheme`/`defineTheme`, `setConfig({ theme })`
  in core, `useVisualLinkerConfig().theme = …` in Vue/Nuxt, system preference.
- `recipes-live-monitoring` — one function from data to connections (`style`
  color/dashed/opacity/animated per status, latency label); in Vue a `computed`
  over `reactive` data, timers only in `onMounted`.