@arcote.tech/arc-process 0.7.28 → 0.7.30

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arcote.tech/arc-process",
   "type": "module",
-  "version": "0.7.28",
+  "version": "0.7.30",
   "private": false,
   "description": "Process description & diagram fragment for Arc framework — generic graph model with profiles, MDX flow components and a deterministic 8-direction layout",
   "main": "./src/index.ts",
@@ -18,11 +18,12 @@
     "@mdx-js/mdx": "^3.1.0",
     "@xyflow/react": "^12.0.0",
     "remark-frontmatter": "^5.0.0",
-    "remark-gfm": "^4.0.0"
+    "remark-gfm": "^4.0.0",
+    "shiki": "^1.24.0"
   },
   "peerDependencies": {
-    "@arcote.tech/arc": "^0.7.28",
-    "@arcote.tech/platform": "^0.7.28",
+    "@arcote.tech/arc": "^0.7.30",
+    "@arcote.tech/platform": "^0.7.30",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
     "typescript": "^5.0.0"

package/src/layout/layout.ts

@@ -163,16 +163,15 @@ export function layoutProcess(input: LayoutInput): ProcessLayout {
     placeGroups(m.groups, s.occId, cx, cy, STEP_W, STEP_H, nodes, edges);
   }
 
-  // --- Szkielet narracji -------------------------------------------------------
-  for (let i = 1; i < steps.length; i++) {
-    const a = steps[i - 1];
-    const b = steps[i];
-    // Równoległe rodzeństwo (ten sam blok, inne lane) i różne tory Entry
-    // nie są sekwencją.
-    if (a.blockId && a.blockId === b.blockId && a.lane !== b.lane) continue;
-    if (a.entryId !== b.entryId) continue;
+  // --- Szkielet narracji (per tor, z fork/join na blokach) ---------------------
+  // Oś główna i każde Entry to osobne tory — blok Entry wtrącony w dokument
+  // nie przerywa ciągłości osi. Bloki Parallel/Branch dostają jawne
+  // rozwidlenie (krok przed blokiem → pierwszy krok KAŻDEGO lane'a) i
+  // scalenie (ostatni krok każdego lane'a → krok po bloku).
+  let bbIdx = 0;
+  const backbone = (a: (typeof steps)[number], b: (typeof steps)[number]) =>
     edges.push({
-      id: `bb:${i}`,
+      id: `bb:${bbIdx++}`,
       source: a.occId,
       target: b.occId,
       color: BACKBONE_COLOR,
@@ -180,6 +179,58 @@ export function layoutProcess(input: LayoutInput): ProcessLayout {
       opacity: 0.6,
       backbone: true,
     });
+
+  const trackMap = new Map<string, (typeof steps)[number][]>();
+  for (const s of steps) {
+    const key = s.entryId ?? "";
+    let track = trackMap.get(key);
+    if (!track) trackMap.set(key, (track = []));
+    track.push(s);
+  }
+
+  interface TrackSeg {
+    block?: string;
+    members: (typeof steps)[number][];
+  }
+  for (const track of trackMap.values()) {
+    // Segmentacja toru: pojedyncze kroki i runy wspólnego blockId.
+    const segs: TrackSeg[] = [];
+    for (const s of track) {
+      const last = segs[segs.length - 1];
+      if (s.blockId && last?.block === s.blockId) last.members.push(s);
+      else segs.push({ block: s.blockId, members: [s] });
+    }
+
+    const laneGroups = (seg: TrackSeg) => {
+      const byLane = new Map<number, (typeof steps)[number][]>();
+      for (const s of seg.members) {
+        let g = byLane.get(s.lane);
+        if (!g) byLane.set(s.lane, (g = []));
+        g.push(s);
+      }
+      return [...byLane.values()];
+    };
+    const firstsOf = (seg: TrackSeg) =>
+      seg.block ? laneGroups(seg).map((g) => g[0]) : [seg.members[0]];
+    const lastsOf = (seg: TrackSeg) =>
+      seg.block
+        ? laneGroups(seg).map((g) => g[g.length - 1])
+        : [seg.members[seg.members.length - 1]];
+
+    for (let i = 0; i < segs.length; i++) {
+      const seg = segs[i];
+      // Sekwencje wewnątrz lane'ów bloku.
+      if (seg.block) {
+        for (const g of laneGroups(seg)) {
+          for (let k = 1; k < g.length; k++) backbone(g[k - 1], g[k]);
+        }
+      }
+      if (i === 0) continue;
+      // Fork/join: każdy koniec poprzedniego segmentu → każdy początek bieżącego.
+      for (const a of lastsOf(segs[i - 1])) {
+        for (const b of firstsOf(seg)) backbone(a, b);
+      }
+    }
   }
 
   // --- Krawędzie continues (Entry → faza, skosem) ------------------------------

package/src/mdx/arc.tsx

@@ -16,14 +16,17 @@ import { kindColor } from "../model/profile";
 import {
   CONTEXT_REF_KIND,
   type Direction,
+  type PinSpec,
   type ResolvedRef,
 } from "../model/types";
 import { resolveContextRef } from "../model/build";
 import { MISSING_COLOR, tint } from "../react/theme";
+import { isPinElement, PinCollectorContext } from "./pin";
 import {
   useFocus,
   useProcessData,
   useRegister,
+  useSelection,
   useStructure,
 } from "./contexts";
 
@@ -43,6 +46,7 @@ function textOf(node: ReactNode): string {
   if (node == null || node === false) return "";
   if (typeof node === "string" || typeof node === "number") return String(node);
   if (Array.isArray(node)) return node.map(textOf).join("");
+  if (isPinElement(node)) return ""; // treść pinów nie wchodzi do etykiety
   if (typeof node === "object" && "props" in (node as unknown as Record<string, unknown>)) {
     return textOf(
       (node as unknown as { props?: { children?: ReactNode } }).props?.children,
@@ -57,6 +61,7 @@ export function Arc(props: ArcProps) {
   const register = useRegister();
   const data = useProcessData();
   const focus = useFocus();
+  const selection = useSelection();
   const { path } = useStructure();
 
   const ref: ResolvedRef | null = context
@@ -64,6 +69,17 @@ export function Arc(props: ArcProps) {
     : (data?.profile.resolveRef(refProps) ?? null);
   const label = textOf(children);
 
+  // Piny z dzieci (<Person>/<Metric>/<Pin>): świeża tablica per render;
+  // dzieci renderują się PRZED efektami, a ArcRefsProvider czyta wpisy w
+  // useEffect — więc mutacja tej tablicy podczas renderu dzieci jest
+  // bezpieczna i occurrence ma komplet pinów, zanim ktokolwiek go odczyta.
+  const pins: PinSpec[] = [];
+  const collectPin = (pin: PinSpec) => {
+    if (!pins.some((p) => p.kind === pin.kind && p.name === pin.name)) {
+      pins.push(pin);
+    }
+  };
+
   // Rejestracja podczas renderu — idempotentna (klucz domId), przeżywa StrictMode.
   register?.({
     domId,
@@ -75,6 +91,7 @@ export function Arc(props: ArcProps) {
       path,
       sides,
       expand,
+      pins,
     },
   });
 
@@ -90,11 +107,17 @@ export function Arc(props: ArcProps) {
       ? `ctx:${resolvedNode.id}`
       : ref?.nodeId;
   const active = !!focusId && focus.focusNodeId === focusId;
-  const color = resolved
+  // Kolor zawsze z ZADEKLAROWANEGO rodzaju (ref.kind) — element nieistniejący
+  // (design-first TODO) zachowuje kolor eventu/komendy itd., a brak w grafie
+  // sygnalizuje wyłącznie kreskowana ramka. Czerwień tylko dla refów
+  // nierozpoznanych w ogóle (złe propsy).
+  const declaredKind = resolved
     ? ref!.kind === CONTEXT_REF_KIND
-      ? (data ? kindColor(data.profile, CONTEXT_REF_KIND) : "#7c3aed")
-      : kindColor(data!.profile, (resolvedNode as { kind: string }).kind)
-    : MISSING_COLOR;
+      ? CONTEXT_REF_KIND
+      : (resolvedNode as { kind: string }).kind
+    : ref?.kind;
+  const color =
+    declaredKind && data ? kindColor(data.profile, declaredKind) : MISSING_COLOR;
 
   return (
     <span
@@ -103,6 +126,7 @@ export function Arc(props: ArcProps) {
       data-arc-node={focusId ?? ""}
       onMouseEnter={() => resolved && focusId && focus.setFocusNodeId(focusId)}
       onMouseLeave={() => focus.setFocusNodeId(null)}
+      onClick={() => selection.selectOcc(domId)}
       title={
         resolved
           ? ref?.method
@@ -117,23 +141,39 @@ export function Arc(props: ArcProps) {
         padding: "1px 8px",
         margin: "0 1px",
         borderRadius: 8,
-        border: `1.5px solid ${color}`,
-        background: resolved ? tint(color, 0.1) : "rgba(225,29,72,0.08)",
+        border: `1.5px ${resolved ? "solid" : "dashed"} ${color}`,
+        background: tint(color, resolved ? 0.1 : 0.05),
         color: "#2a173f",
         fontWeight: 600,
         fontSize: "0.92em",
         cursor: "pointer",
         boxShadow: active ? `0 0 0 2px ${color}` : "none",
         whiteSpace: "nowrap",
+        opacity: resolved ? 1 : 0.85,
       }}
     >
       <span
         style={{ width: 7, height: 7, borderRadius: 2, background: color }}
       />
-      {label || ref?.nodeId || "?"}
-      {ref?.method ? (
-        <span style={{ color: "#6b5b86", fontWeight: 500 }}>·{ref.method.name}</span>
-      ) : null}
+      <PinCollectorContext.Provider value={collectPin}>
+        {label || ref?.nodeId || "?"}
+        {ref?.method ? (
+          <span style={{ color: "#6b5b86", fontWeight: 500 }}>·{ref.method.name}</span>
+        ) : null}
+        {renderPins(children)}
+      </PinCollectorContext.Provider>
     </span>
   );
 }
+
+/** Wyrenderuj z dzieci WYŁĄCZNIE komponenty pinów (tekst poszedł do etykiety). */
+function renderPins(children: ReactNode): ReactNode {
+  if (children == null || typeof children !== "object") return null;
+  if (Array.isArray(children)) {
+    return children.map((c, i) =>
+      isPinElement(c) ? <span key={i}>{c}</span> : renderPins(c),
+    );
+  }
+  if (isPinElement(children)) return children;
+  return null;
+}

package/src/mdx/contexts.tsx

@@ -40,6 +40,17 @@ export interface RegEntry {
 export const RegisterContext = createContext<((entry: RegEntry) => void) | null>(null);
 export const useRegister = () => useContext(RegisterContext);
 
+/** Wybór kroku → drawer szczegółów (occId lub null = zamknięty). */
+export interface SelectionState {
+  selectedOcc: string | null;
+  selectOcc: (occId: string | null) => void;
+}
+export const SelectionContext = createContext<SelectionState>({
+  selectedOcc: null,
+  selectOcc: () => {},
+});
+export const useSelection = () => useContext(SelectionContext);
+
 /** Stan widoku + akcje (toggle rozwinięć / zwinięć kontekstów). */
 export interface ViewStateActions {
   state: ProcessViewState;

package/src/mdx/mdx-view.tsx

@@ -11,6 +11,7 @@ import { useEffect, useState, type ComponentType, type ReactNode } from "react";
 import * as runtime from "react/jsx-runtime";
 import type { Occurrence } from "../model/types";
 import { Arc } from "./arc";
+import { Metric, Person, Pin } from "./pin";
 import { Branch, Continue, Entry, Lane, Note, Parallel, Step } from "./structure";
 import { ArcRefsProvider } from "./ref-context";
 import { GLASS } from "../react/theme";
@@ -26,6 +27,9 @@ const mdxComponents = {
   Entry,
   Continue,
   Note,
+  Pin,
+  Person,
+  Metric,
   h1: (p: ElProps) => (
     <h1 style={{ fontSize: 24, color: GLASS.text, margin: "4px 0 12px" }} {...p} />
   ),

package/src/mdx/pin.tsx

@@ -0,0 +1,101 @@
+/**
+ * Przypięcia (`<Pin>`, `<Person>`, `<Metric>`) — deklarowane w MDX WEWNĄTRZ
+ * `<Arc>`:
+ *
+ * ```mdx
+ * <Arc aggregate="leads" mutationMethod="submitLead">
+ *   zgłoszenie leada<Person name="prospekt"/><Metric name="leads.submitted"/>
+ * </Arc>
+ * ```
+ *
+ * Pin rejestruje się u rodzica (kolektor z kontekstu `<Arc>`) podczas
+ * renderu i renderuje mini-chip inline. Rodzaje pinów definiuje PROFIL
+ * (`pinKinds`); wartości rozwiązują się z generycznego katalogu
+ * (arc.catalog.yml) po `name` — w modelu, nie tutaj. `Person`/`Metric` to
+ * cienkie aliasy generycznego `Pin`, przyszłe rodzaje nie wymagają zmian.
+ */
+
+import { createContext, useContext, type ReactNode } from "react";
+import type { PinSpec } from "../model/types";
+import { GLASS, tint } from "../react/theme";
+import { useProcessData } from "./contexts";
+
+/** Kolektor pinów dostarczany przez `<Arc>` swoim dzieciom. */
+export const PinCollectorContext = createContext<((pin: PinSpec) => void) | null>(
+  null,
+);
+
+function textOf(node: ReactNode): string {
+  if (node == null || node === false) return "";
+  if (typeof node === "string" || typeof node === "number") return String(node);
+  if (Array.isArray(node)) return node.map(textOf).join("");
+  return "";
+}
+
+export interface PinProps {
+  /** Rodzaj przypięcia (klucz `pinKinds` profilu), np. "persona", "metric". */
+  type: string;
+  /** Nazwa wpisu katalogu (arc.catalog.yml). */
+  name: string;
+  /** Etykieta (fallback: label z katalogu → name). */
+  label?: string;
+  children?: ReactNode;
+}
+
+export function Pin({ type, name, label, children }: PinProps) {
+  const collect = useContext(PinCollectorContext);
+  const data = useProcessData();
+  const resolvedLabel = label ?? (textOf(children) || undefined);
+
+  collect?.({ kind: type, name, label: resolvedLabel });
+
+  const spec = data?.profile.pinKinds?.[type];
+  const color = spec?.color ?? "#64748b";
+  return (
+    <span
+      data-arc-pin={type}
+      title={`${spec?.label ?? type}: ${name}`}
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        gap: 3,
+        marginLeft: 4,
+        padding: "0 6px",
+        borderRadius: 99,
+        border: `1px solid ${tint(color, 0.55)}`,
+        background: tint(color, 0.08),
+        color: GLASS.textMuted,
+        fontSize: "0.78em",
+        fontWeight: 600,
+        whiteSpace: "nowrap",
+        verticalAlign: "baseline",
+      }}
+    >
+      {spec?.icon ?? "◦"} {resolvedLabel ?? name}
+    </span>
+  );
+}
+
+/** Persona-wykonawca kroku. */
+export function Person(props: Omit<PinProps, "type">) {
+  return <Pin type="persona" {...props} />;
+}
+
+/** Metryka przypięta do kroku. */
+export function Metric(props: Omit<PinProps, "type">) {
+  return <Pin type="metric" {...props} />;
+}
+
+// Znacznik dla textOf w <Arc> — treść pinów nie wchodzi do etykiety kroku.
+(Pin as unknown as Record<string, unknown>).__arcPin = true;
+(Person as unknown as Record<string, unknown>).__arcPin = true;
+(Metric as unknown as Record<string, unknown>).__arcPin = true;
+
+/** Czy węzeł React jest komponentem przypięcia (pomijany w etykiecie). */
+export function isPinElement(node: unknown): boolean {
+  const type = (node as { type?: unknown } | null)?.type;
+  return (
+    typeof type === "function" &&
+    (type as unknown as Record<string, unknown>).__arcPin === true
+  );
+}

package/src/model/build.ts

@@ -21,12 +21,14 @@ import {
   type NoteOccurrence,
   type Occurrence,
   type PathSeg,
+  type PinSpec,
   type ProcessConnector,
   type ProcessGraph,
   type ProcessModel,
   type ProcessNode,
   type ProcessRelation,
   type ProcessStep,
+  type ResolvedPin,
   type StepOccurrence,
 } from "./types";
 
@@ -212,36 +214,62 @@ function assignDepthLane(
     .filter((s) => !s.entryId)
     .map((s) => s.lane);
   const maxMainLane = mainLanes.length ? Math.max(...mainLanes) : 0;
-  let aboveCount = 0;
-  let belowCount = 0;
 
-  entryOrder.forEach((entryId, k) => {
+  interface EntryPlan {
+    e: EntryBlock;
+    targetDepth: number;
+    targetOcc?: string;
+    toPhase?: string;
+  }
+  const plans: EntryPlan[] = entryOrder.map((entryId) => {
     const e = entries.get(entryId)!;
-    const target = (e.to !== undefined ? phaseStart.get(e.to) : undefined) ?? firstPhase;
-    const targetDepth = target?.depth ?? 0;
-    const L = e.stepIdx.length;
-    const start = Math.max(0, targetDepth - L);
-    const above = k % 2 === 0;
-    const lane = above ? -(1 + aboveCount++) : maxMainLane + 1 + belowCount++;
-    e.stepIdx.forEach((idx, i) => {
+    const target =
+      (e.to !== undefined ? phaseStart.get(e.to) : undefined) ?? firstPhase;
+    return {
+      e,
+      targetDepth: target?.depth ?? 0,
+      targetOcc: target?.occId,
+      toPhase: e.to,
+    };
+  });
+
+  // Wyprzedzenie: oś główna przesuwa się w prawo na tyle, by KAŻDY łańcuch
+  // Entry zmieścił się PRZED swoją fazą docelową — krawędź „continues” zawsze
+  // biegnie w prawo, nigdy wstecz przez diagram.
+  const maxLead = Math.max(
+    0,
+    ...plans.map((p) => p.e.stepIdx.length - p.targetDepth),
+  );
+  if (maxLead > 0) {
+    for (const s of steps) if (!s.entryId) s.depth += maxLead;
+    for (const p of plans) p.targetDepth += maxLead;
+  }
+
+  const placeEntry = (p: EntryPlan, lane: number) => {
+    const L = p.e.stepIdx.length;
+    const start = Math.max(0, p.targetDepth - L);
+    p.e.stepIdx.forEach((idx, i) => {
       steps[idx].depth = start + i;
       steps[idx].lane = lane;
     });
-    if (target && e.to !== undefined && L > 0) {
-      continueEdges.push({
-        fromOcc: steps[e.stepIdx[L - 1]].occId,
-        toOcc: target.occId,
-        phaseId: e.to,
-      });
-    } else if (target && L > 0) {
-      // Entry bez Continue → wpięcie w pierwszą fazę dokumentu.
+    if (p.targetOcc && L > 0) {
       continueEdges.push({
-        fromOcc: steps[e.stepIdx[L - 1]].occId,
-        toOcc: target.occId,
-        phaseId: "",
+        fromOcc: steps[p.e.stepIdx[L - 1]].occId,
+        toOcc: p.targetOcc,
+        phaseId: p.toPhase ?? "",
       });
     }
-  });
+  };
+
+  // Tory naprzemiennie nad/pod osią (kolejność dokumentu), a w obrębie strony
+  // wejścia celujące dalej w prawo lądują bliżej osi — ich krawędzie
+  // „continues” nie przecinają wtedy torów pozostałych wejść.
+  const above = plans.filter((_, k) => k % 2 === 0);
+  const below = plans.filter((_, k) => k % 2 === 1);
+  above.sort((a, b) => b.targetDepth - a.targetDepth);
+  below.sort((a, b) => b.targetDepth - a.targetDepth);
+  above.forEach((p, i) => placeEntry(p, -(1 + i)));
+  below.forEach((p, i) => placeEntry(p, maxMainLane + 1 + i));
 
   return continueEdges;
 }
@@ -381,6 +409,28 @@ export function buildProcessModel(input: BuildModelInput): ProcessModel {
     return nodeById.get(nodeId);
   };
 
+  // Rozwiązywanie pinów przeciw katalogowi: rodzaj pinu (profil) wskazuje
+  // rodzaj wpisu katalogu (catalogKind, fallback: klucz pinu), wpis po name.
+  const catalogByKey = new Map(
+    (graph.catalog ?? []).map((c) => [`${c.kind} ${c.name}`, c]),
+  );
+  const resolvePin = (pin: PinSpec): ResolvedPin => {
+    const spec = profile.pinKinds?.[pin.kind];
+    const catalogKind = spec?.catalogKind ?? pin.kind;
+    const entry = catalogByKey.get(`${catalogKind} ${pin.name}`);
+    const label =
+      pin.label ??
+      (typeof entry?.data.label === "string" ? entry.data.label : undefined) ??
+      pin.name;
+    return {
+      kind: pin.kind,
+      name: pin.name,
+      label,
+      data: entry?.data,
+      resolved: !!entry,
+    };
+  };
+
   // 1) Kroki — jeden na wystąpienie.
   const steps: ProcessStep[] = stepOccs.map((o, i) => {
     const node = o.ref ? resolve(o.ref.nodeId, o.ref.kind) : undefined;
@@ -396,6 +446,7 @@ export function buildProcessModel(input: BuildModelInput): ProcessModel {
       attachments: {},
       sides: o.sides,
       expand: o.expand,
+      pins: (o.pins ?? []).map(resolvePin),
       notes: (notesFor.get(o.occId) ?? []).map((n) => ({
         occId: n.occId,
         side: n.side ?? ("N" as const),

package/src/model/collapse.ts

@@ -115,6 +115,8 @@ function groupStep(
     },
     label: ctx.title ?? ctx.name ?? ctx.id,
     attachments: {},
+    // Box kontekstu nie agreguje pinów członków (v1) — szczegóły po otwarciu.
+    pins: [],
     notes: members.flatMap((m) => m.notes),
     depth: Math.min(...members.map((m) => m.depth)),
     lane: first.lane,

package/src/model/profile.ts

@@ -54,6 +54,19 @@ export interface AttachmentGroupSpec {
   label?: string;
 }
 
+/** Rodzaj przypięcia (Pin) — wygląd badge'a i mapowanie na katalog. */
+export interface PinKindSpec {
+  icon: string;
+  color: string;
+  /** Etykieta rodzaju (fallback: klucz). */
+  label?: string;
+  /**
+   * Rodzaj wpisu katalogu (klucz YAML), z którego pin się rozwiązuje —
+   * np. pin "persona" czyta wpisy "personas". Fallback: klucz pinu.
+   */
+  catalogKind?: string;
+}
+
 export interface ProcessProfile {
   id: string;
   /** Rodzaje nodów tego profilu. */
@@ -62,6 +75,8 @@ export interface ProcessProfile {
   relations: Record<string, RelationSpec>;
   /** Grupy doczepień (badge/rozwinięcia) wokół kroków. */
   attachmentGroups: Record<string, AttachmentGroupSpec>;
+  /** Rodzaje przypięć (Pin) — persony, metryki, przyszłe. */
+  pinKinds?: Record<string, PinKindSpec>;
   /**
    * Mapuje propsy `<Arc>` na referencję do noda (bez walidacji istnienia —
    * tę robi model przeciw grafowi). Zwraca null, gdy propsy nie zawierają

package/src/model/types.ts

@@ -70,11 +70,23 @@ export interface ContextInfo {
   hasCard?: boolean;
 }
 
+/**
+ * Wpis generycznego katalogu deklaracji (arc.catalog.yml, ładowany przez
+ * narzędzie-hosta np. arc-map) — persony, metryki i przyszłe rodzaje.
+ */
+export interface CatalogEntry {
+  kind: string;
+  name: string;
+  /** Pełny wpis YAML: name, label?, color?, description?, …dowolne pola. */
+  data: Record<string, unknown>;
+}
+
 /** Kompletny graf wejściowy diagramu. */
 export interface ProcessGraph {
   nodes: ProcessNode[];
   relations: ProcessRelation[];
   contexts?: ContextInfo[];
+  catalog?: CatalogEntry[];
 }
 
 /** Pusty graf — wszystkie referencje będą czerwonymi chipami TODO. */
@@ -125,6 +137,27 @@ export interface PathSeg {
 // Wystąpienia (rejestrowane przez MDX w kolejności dokumentu)
 // ---------------------------------------------------------------------------
 
+/**
+ * Przypięcie zadeklarowane w MDX wewnątrz `<Arc>` (np. `<Person name>`,
+ * `<Metric name>`) — rodzaj z profilu, wpis rozwiązywany z katalogu po name.
+ */
+export interface PinSpec {
+  kind: string;
+  name: string;
+  /** Etykieta z MDX (fallback: label z katalogu → name). */
+  label?: string;
+}
+
+/** Przypięcie rozwiązane przeciw katalogowi grafu. */
+export interface ResolvedPin {
+  kind: string;
+  name: string;
+  label: string;
+  /** Dane wpisu katalogu (color, description, …), gdy rozwiązany. */
+  data?: Record<string, unknown>;
+  resolved: boolean;
+}
+
 /** Wystąpienie kroku — jedno na każdy `<Arc>` w narracji. */
 export interface StepOccurrence {
   type: "step";
@@ -136,6 +169,8 @@ export interface StepOccurrence {
   sides?: Partial<Record<string, Direction>>;
   /** Grupy relacji otwarte na starcie (`<Arc expand={["mutates"]}>`). */
   expand?: string[];
+  /** Przypięcia z komponentów wewnątrz `<Arc>` (Person/Metric/Pin). */
+  pins?: PinSpec[];
 }
 
 /** Marker `<Continue to="faza"/>` — zamyka bieżące Entry, wskazuje cel. */
@@ -184,6 +219,8 @@ export interface ProcessStep {
   sides?: Partial<Record<string, Direction>>;
   /** Grupy otwarte na starcie (z MDX). */
   expand?: string[];
+  /** Przypięcia rozwiązane przeciw katalogowi (persony, metryki, …). */
+  pins: ResolvedPin[];
   notes: StepNote[];
   /** Pozycja pozioma (czas / głębokość zależności), 0-based. */
   depth: number;