@arcote.tech/arc-process 0.7.29 → 0.7.31

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arcote.tech/arc-process",
   "type": "module",
-  "version": "0.7.29",
+  "version": "0.7.31",
   "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",
@@ -22,8 +22,8 @@
     "shiki": "^1.24.0"
   },
   "peerDependencies": {
-    "@arcote.tech/arc": "^0.7.29",
-    "@arcote.tech/platform": "^0.7.29",
+    "@arcote.tech/arc": "^0.7.31",
+    "@arcote.tech/platform": "^0.7.31",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
     "typescript": "^5.0.0"

package/src/layout/layout.ts

@@ -323,7 +323,10 @@ export function layoutProcess(input: LayoutInput): ProcessLayout {
     const semantics = spec?.semantics ?? "in";
     const from = semantics === "in" ? tId : sId;
     const to = semantics === "in" ? sId : tId;
-    if (semantics === "out" && depthOf(to) < depthOf(from)) continue; // wsteczne wyjście → szum
+    // Nie rysujemy relacji biegnącej prawo→lewo: gdy cel jest w kolumnie
+    // wcześniejszej LUB tej samej co źródło (strzałka wsteczna albo pionowa
+    // to szum wizualny — przepływ czyta się lewo→prawo).
+    if (depthOf(to) <= depthOf(from)) continue;
     const key = `${from}->${to}:${r.kind}`;
     if (seenEdge.has(key)) continue;
     seenEdge.add(key);

package/src/mdx/arc.tsx

@@ -95,17 +95,26 @@ export function Arc(props: ArcProps) {
     },
   });
 
+  // Most token→realId: gdy konsument poda `resolveNodeId` (np. canvas grafu
+  // wiedzy), rozwiązanie i focusId idą przez niego — chip i nod dzielą tę samą
+  // przestrzeń id. Brak mostu = domyślne dopasowanie po `graph.nodes`.
+  const mappedId =
+    ref && data?.resolveNodeId && ref.kind !== CONTEXT_REF_KIND
+      ? data.resolveNodeId(ref)
+      : null;
   const resolvedNode =
     ref && data
       ? ref.kind === CONTEXT_REF_KIND
         ? resolveContextRef(data.graph.contexts ?? [], ref.nodeId)
-        : data.graph.nodes.find((n) => n.id === ref.nodeId)
+        : mappedId
+          ? { id: mappedId, kind: ref.kind, label: label }
+          : data.graph.nodes.find((n) => n.id === ref.nodeId)
       : undefined;
   const resolved = !!resolvedNode;
   const focusId =
     ref?.kind === CONTEXT_REF_KIND && resolvedNode && "id" in resolvedNode
       ? `ctx:${resolvedNode.id}`
-      : ref?.nodeId;
+      : (mappedId ?? ref?.nodeId);
   const active = !!focusId && focus.focusNodeId === focusId;
   // Kolor zawsze z ZADEKLAROWANEGO rodzaju (ref.kind) — element nieistniejący
   // (design-first TODO) zachowuje kolor eventu/komendy itd., a brak w grafie

package/src/mdx/contexts.tsx

@@ -2,13 +2,27 @@
 
 import { createContext, useContext } from "react";
 import type { ProcessProfile } from "../model/profile";
-import type { Direction, Occurrence, PathSeg, ProcessGraph } from "../model/types";
+import type {
+  Direction,
+  Occurrence,
+  PathSeg,
+  ProcessGraph,
+  ResolvedRef,
+} from "../model/types";
 import type { ExpansionKey, ProcessViewState } from "../state/view-state";
 
 /** Graf + profil — walidacja referencji i kolory chipów. */
 export interface ProcessData {
   graph: ProcessGraph;
   profile: ProcessProfile;
+  /**
+   * Opcjonalny MOST token→rzeczywiste id noda renderera. Gdy konsument (np.
+   * canvas grafu wiedzy BMF) go poda, `<Arc>` liczy `focusId` przez niego —
+   * dzięki temu hover chipa i hover noda operują w TEJ SAMEJ przestrzeni id,
+   * a dwukierunkowy highlight działa bez zgadywania. Brak = zachowanie
+   * domyślne (dopasowanie po `graph.nodes`), jak w arc-map.
+   */
+  resolveNodeId?: (ref: ResolvedRef) => string | null;
 }
 export const ProcessDataContext = createContext<ProcessData | null>(null);
 export const useProcessData = () => useContext(ProcessDataContext);

package/src/mdx/declare.tsx

@@ -0,0 +1,147 @@
+/**
+ * `<DeclareNode>` / `<DeclareRelation>` — deklaracja nodów i relacji INLINE
+ * w prozie MDX (nie tylko referencja istniejących).
+ *
+ * Generyczne prymitywy rdzenia: rejestrują wystąpienie (jak `<Arc>`/`<Note>`),
+ * uczestniczą w focusie (hover chip↔nod) i selekcji (klik→drawer), a renderer
+ * diagramu (np. canvas grafu wiedzy BMF) decyduje, jak je pokazać. Konsument
+ * owija je cienkim aliasem (`<Node>`/`<Rel>` dokumentów).
+ */
+
+import { useId, type ReactNode } from "react";
+import { kindColor } from "../model/profile";
+import { useFocus, useProcessData, useRegister, useSelection } from "./contexts";
+import { MISSING_COLOR, tint } from "../react/theme";
+
+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 (typeof node === "object" && "props" in (node as unknown as Record<string, unknown>)) {
+    return textOf(
+      (node as unknown as { props?: { children?: ReactNode } }).props?.children,
+    );
+  }
+  return "";
+}
+
+export interface DeclareNodeProps {
+  /** Id noda (stabilny). Gdy brak — pochodzi z etykiety. */
+  id?: string;
+  /** Rodzaj (kind) — kolor/ikona z profilu. */
+  kind?: string;
+  /** Etykieta wyświetlana (fallback: children). */
+  label?: string;
+  children?: ReactNode;
+  /** Dowolne dodatkowe dane noda (props domeny). */
+  [k: string]: unknown;
+}
+
+function slug(s: string): string {
+  return s.toLowerCase().trim().replace(/\s+/g, "-");
+}
+
+export function DeclareNode(props: DeclareNodeProps) {
+  const { id, kind, label, children, ...rest } = props;
+  const domId = useId();
+  const register = useRegister();
+  const data = useProcessData();
+  const focus = useFocus();
+  const selection = useSelection();
+
+  const text = label ?? textOf(children);
+  const nodeId = id ?? `eph:${slug(text || domId)}`;
+  const nodeKind = kind ?? "ephemeral";
+
+  register?.({
+    domId,
+    occurrence: {
+      type: "declare-node",
+      occId: domId,
+      node: { id: nodeId, kind: nodeKind, label: text || nodeId, meta: rest },
+    },
+  });
+
+  const active = focus.focusNodeId === nodeId;
+  const color = data ? kindColor(data.profile, nodeKind) : MISSING_COLOR;
+
+  return (
+    <span
+      data-arc-id={domId}
+      data-arc-node={nodeId}
+      onMouseEnter={() => focus.setFocusNodeId(nodeId)}
+      onMouseLeave={() => focus.setFocusNodeId(null)}
+      onClick={() => selection.selectOcc(domId)}
+      title={`${nodeKind}: ${nodeId}`}
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        gap: 4,
+        padding: "1px 8px",
+        margin: "0 1px",
+        borderRadius: 8,
+        border: `1.5px solid ${color}`,
+        background: tint(color, 0.1),
+        color: "#2a173f",
+        fontWeight: 600,
+        fontSize: "0.92em",
+        cursor: "pointer",
+        boxShadow: active ? `0 0 0 2px ${color}` : "none",
+        whiteSpace: "nowrap",
+      }}
+    >
+      <span style={{ width: 7, height: 7, borderRadius: 2, background: color }} />
+      {text || nodeId}
+    </span>
+  );
+}
+
+export interface DeclareRelationProps {
+  from: string;
+  to: string;
+  kind?: string;
+  dir?: "out" | "in" | "both";
+  label?: string;
+}
+
+export function DeclareRelation({
+  from,
+  to,
+  kind = "rel",
+  dir = "out",
+  label,
+}: DeclareRelationProps) {
+  const domId = useId();
+  const register = useRegister();
+  const data = useProcessData();
+
+  register?.({
+    domId,
+    occurrence: { type: "relation", occId: domId, from, to, kind, dir, label },
+  });
+
+  const color = data ? kindColor(data.profile, kind) : MISSING_COLOR;
+  const arrow = dir === "in" ? "←" : dir === "both" ? "↔" : "→";
+  return (
+    <span
+      data-arc-id={domId}
+      title={`${from} ${arrow} ${to}`}
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        gap: 4,
+        padding: "1px 8px",
+        margin: "0 1px",
+        borderRadius: 999,
+        border: `1px solid ${tint(color, 0.55)}`,
+        background: tint(color, 0.08),
+        color: "#2a173f",
+        fontSize: "0.85em",
+        fontWeight: 600,
+        whiteSpace: "nowrap",
+      }}
+    >
+      {from} {label ? `—${label}${arrow}` : arrow} {to}
+    </span>
+  );
+}

package/src/mdx/mdx-view.tsx

@@ -87,12 +87,18 @@ export function parseProcessFrontmatter(mdx: string): ProcessFrontmatter {
 export function MdxView({
   mdx,
   onOccurrences,
+  components,
 }: {
   mdx: string;
   onOccurrences: (occurrences: Occurrence[]) => void;
+  /**
+   * Dodatkowe / nadpisujące komponenty MDX (np. Ref/Node/Rel/Metric/Formula
+   * konsumenta — dokumenty BMF). Scalane nad domyślnym słownikiem procesu.
+   */
+  components?: Record<string, ComponentType<Record<string, unknown>>>;
 }) {
   const [Comp, setComp] = useState<ComponentType<{
-    components: typeof mdxComponents;
+    components: Record<string, unknown>;
   }> | null>(null);
   const [error, setError] = useState<string | null>(null);
 
@@ -106,7 +112,7 @@ export function MdxView({
     } as Parameters<typeof evaluate>[1])
       .then((mod) => {
         if (!cancelled) {
-          setComp(() => mod.default as ComponentType<{ components: typeof mdxComponents }>);
+          setComp(() => mod.default as ComponentType<{ components: Record<string, unknown> }>);
         }
       })
       .catch((e) => {
@@ -127,9 +133,10 @@ export function MdxView({
   }
   if (!Comp) return <div style={{ color: GLASS.textMuted }}>Renderuję dokument…</div>;
 
+  const merged = components ? { ...mdxComponents, ...components } : mdxComponents;
   return (
     <ArcRefsProvider onOccurrences={onOccurrences}>
-      <Comp components={mdxComponents} />
+      <Comp components={merged} />
     </ArcRefsProvider>
   );
 }

package/src/mdx/ref-context.tsx

@@ -41,7 +41,11 @@ export function ArcRefsProvider({
           ? (o.ref?.key ?? `?${o.occId}`)
           : o.type === "continue"
             ? `cont:${o.to}`
-            : `note:${o.occId}`,
+            : o.type === "note"
+              ? `note:${o.occId}`
+              : o.type === "declare-node"
+                ? `decl:${o.node.id}`
+                : `rel:${o.from}->${o.to}:${o.kind}`,
       )
       .join("|");
     if (sig === lastSig.current) return;

package/src/model/types.ts

@@ -190,7 +190,46 @@ export interface NoteOccurrence {
   path?: PathSeg[];
 }
 
-export type Occurrence = StepOccurrence | ContinueOccurrence | NoteOccurrence;
+/**
+ * Deklaracja noda INLINE w MDX (`<Node>` dokumentów) — nod istniejący tylko w
+ * tej narracji (efemeryczny). Rejestrowany jak krok; renderer diagramu (canvas
+ * grafu wiedzy) decyduje, jak go pokazać. `buildProcessModel` (profil
+ * procesowy) go ignoruje.
+ */
+export interface DeclareNodeOccurrence {
+  type: "declare-node";
+  occId: string;
+  node: {
+    id: string;
+    kind: string;
+    label: string;
+    meta?: Record<string, unknown>;
+  };
+  path?: PathSeg[];
+}
+
+/**
+ * Deklaracja relacji INLINE w MDX (`<Rel from to>` dokumentów) — krawędź między
+ * dowolnymi nodami. Konsumowana przez renderer grafu wiedzy; profil procesowy
+ * ją ignoruje.
+ */
+export interface RelationOccurrence {
+  type: "relation";
+  occId: string;
+  from: string;
+  to: string;
+  kind: string;
+  dir?: "out" | "in" | "both";
+  label?: string;
+  path?: PathSeg[];
+}
+
+export type Occurrence =
+  | StepOccurrence
+  | ContinueOccurrence
+  | NoteOccurrence
+  | DeclareNodeOccurrence
+  | RelationOccurrence;
 
 // ---------------------------------------------------------------------------
 // Model wynikowy

package/src/react/index.ts

@@ -3,6 +3,12 @@
  */
 
 export { ProcessDiagram, type ProcessDiagramProps } from "./process-diagram";
+export {
+  ProseInteractionRoot,
+  type ProseInteractionRootProps,
+  type ProseRootRenderApi,
+} from "./prose-root";
+export { ProcessFlowCanvas, type ProcessFlowCanvasProps } from "./process-flow-canvas";
 export { ProcessDrawer, type ProcessDrawerProps, type SourceProvider } from "./drawer";
 export { makeNodeTypes } from "./nodes";
 export { Pin, Person, Metric, type PinProps } from "../mdx/pin";
@@ -15,6 +21,12 @@ export {
 } from "./context-card";
 export { GLASS, BG_GRADIENT, MISSING_COLOR, tint } from "./theme";
 export { Arc, type ArcProps } from "../mdx/arc";
+export {
+  DeclareNode,
+  DeclareRelation,
+  type DeclareNodeProps,
+  type DeclareRelationProps,
+} from "../mdx/declare";
 export {
   Branch,
   Continue,

package/src/react/nodes.tsx

@@ -223,7 +223,11 @@ export function makeNodeTypes(profile: ProcessProfile) {
           </span>
         </div>
         <div style={{ fontSize: 10, color: GLASS.textMuted }}>
-          {KIND_ICON[declaredKind] ?? "•"} {declaredKind}
+          {KIND_ICON[declaredKind] ?? "•"}{" "}
+          {/* NAZWA elementu (id) zamiast słowa-rodzaju — rodzaj widać po
+              ikonie i kolorze, a nazwa mówi, którego elementu dotyczy krok.
+              Dla nieistniejących (TODO) pada na nazwę z referencji. */}
+          {s.node?.id ?? s.ref?.nodeId ?? declaredKind}
           {s.method ? ` · ${s.method.name}` : ""}
         </div>
         <PinBadges profile={profile} pins={s.pins} />

package/src/react/process-diagram.tsx

@@ -1,54 +1,21 @@
 /**
  * `ProcessDiagram` — fetch-free viewer procesu z MDX.
  *
- * Proza (MDX z chipami) po lewej, diagram ReactFlow po prawej. MDX przychodzi
- * propsem; `graph` jest opcjonalny — domyślnie pusty, więc każda referencja
- * renderuje się jako czerwony chip TODO (design-first).
+ * Proza (MDX z chipami) po lewej, diagram ReactFlow po prawej. Cienki wrapper
+ * nad wspólnym rdzeniem: `ProseInteractionRoot` (providery + proza + stan) +
+ * `ProcessFlowCanvas` (procesowy renderer). Publiczne API bez zmian.
  *
  * Pipeline: MDX → wystąpienia (DOM-order) → buildProcessModel →
- * collapseContexts (hierarchia kontekstów) → layoutProcess (8 kierunków,
- * track sizing) → ReactFlow. Stan otwarć: MDX deklaruje start, czytelnik
- * toggluje, persystencja przez `store` (localStorage / agregat).
+ * collapseContexts → layoutProcess (8 kierunków) → ReactFlow. Stan otwarć:
+ * MDX deklaruje start, czytelnik toggluje, persystencja przez `store`.
  */
 
-import "@xyflow/react/dist/style.css";
-
-import {
-  Background,
-  Controls,
-  MarkerType,
-  MiniMap,
-  ReactFlow,
-  type Edge,
-  type Node,
-} from "@xyflow/react";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { buildProcessModel } from "../model/build";
-import { collapseContexts } from "../model/collapse";
-import { layoutProcess, type DiagramEdge, type DiagramNode } from "../layout/layout";
-import { kindColor, type ProcessProfile } from "../model/profile";
-import {
-  EMPTY_GRAPH,
-  type Occurrence,
-  type ProcessGraph,
-  type ProcessStep,
-} from "../model/types";
-import {
-  initialViewState,
-  toggleContext as toggleContextState,
-  toggleGroup as toggleGroupState,
-  type ProcessViewState,
-} from "../state/view-state";
+import type { ProcessProfile } from "../model/profile";
+import type { ProcessGraph } from "../model/types";
 import type { ProcessViewStore } from "../state/store";
-import { MdxView, parseProcessFrontmatter } from "../mdx/mdx-view";
-import {
-  FocusContext,
-  ProcessDataContext,
-  SelectionContext,
-  ViewStateContext,
-} from "../mdx/contexts";
-import { makeNodeTypes } from "./nodes";
-import { ProcessDrawer, type SourceProvider } from "./drawer";
+import { ProseInteractionRoot } from "./prose-root";
+import { ProcessFlowCanvas } from "./process-flow-canvas";
+import type { SourceProvider } from "./drawer";
 import { GLASS } from "./theme";
 
 export interface ProcessDiagramProps {
@@ -76,44 +43,10 @@ export interface ProcessDiagramProps {
   sourceProvider?: SourceProvider;
 }
 
-function rfNode(n: DiagramNode): Node {
-  return {
-    id: n.id,
-    type: n.type,
-    position: { x: n.x, y: n.y },
-    width: n.w,
-    height: n.h,
-    data: n.data,
-    draggable: false,
-    selectable: n.type !== "context-group",
-    zIndex: n.type === "context-group" ? -1 : undefined,
-  };
-}
-
-function rfEdge(e: DiagramEdge): Edge {
-  return {
-    id: e.id,
-    source: e.source,
-    target: e.target,
-    label: e.label,
-    style: {
-      stroke: e.color,
-      strokeWidth: 1.5,
-      opacity: e.opacity ?? 0.75,
-      strokeDasharray: e.dashed ? "4 3" : undefined,
-    },
-    labelStyle: { fill: e.color, fontSize: 9, fontWeight: 600 },
-    labelBgStyle: { fill: "#fff", fillOpacity: 0.8 },
-    markerEnd: e.backbone
-      ? undefined
-      : { type: MarkerType.ArrowClosed, color: e.color },
-  };
-}
-
 export function ProcessDiagram({
   mdx,
   profile,
-  graph = EMPTY_GRAPH,
+  graph,
   store,
   docId,
   title,
@@ -121,218 +54,47 @@ export function ProcessDiagram({
   homeContextId,
   sourceProvider,
 }: ProcessDiagramProps) {
-  const [occurrences, setOccurrences] = useState<Occurrence[]>([]);
-  const [viewState, setViewState] = useState<ProcessViewState | null>(null);
-  const [focusNodeId, setFocusNodeId] = useState<string | null>(null);
-  const [scrollToKey, setScrollToKey] = useState<string | null>(null);
-  const [selectedOcc, setSelectedOcc] = useState<string | null>(null);
-  const proseRef = useRef<HTMLDivElement>(null);
-
-  const frontmatter = useMemo(() => parseProcessFrontmatter(mdx), [mdx]);
-  const docKey = docId ?? title ?? frontmatter.title ?? mdx.slice(0, 48);
-  const collapsedByDefault =
-    defaultCollapsed ?? (frontmatter.collapse ?? "all") === "all";
-  const home = homeContextId ?? frontmatter.context;
-
-  // Reset przy zmianie dokumentu.
-  useEffect(() => {
-    setOccurrences([]);
-    setViewState(null);
-    setSelectedOcc(null);
-  }, [mdx]);
-
-  const model = useMemo(
-    () => buildProcessModel({ graph, profile, occurrences }),
-    [graph, profile, occurrences],
-  );
-
-  // Kontekst domowy: id lub nazwa z frontmatter/propsa.
-  const homeId = useMemo(() => {
-    if (!home) return undefined;
-    const ctxs = graph.contexts ?? [];
-    return (ctxs.find((c) => c.id === home) ?? ctxs.find((c) => c.name === home))?.id;
-  }, [graph, home]);
-
-  // Stan efektywny: jawny stan czytelnika → zapisany w store → startowy z MDX.
-  const effectiveState = useMemo<ProcessViewState>(() => {
-    if (viewState) return viewState;
-    const stored = store?.load(docKey);
-    if (stored) return stored;
-    return initialViewState(model);
-  }, [viewState, store, docKey, model]);
-
-  const updateState = useCallback(
-    (next: ProcessViewState) => {
-      setViewState(next);
-      store?.save(docKey, next);
-    },
-    [store, docKey],
-  );
-
-  const collapse = useMemo(
-    () =>
-      collapseContexts(model, {
-        contexts: graph.contexts ?? [],
-        state: effectiveState,
-        defaultCollapsed: collapsedByDefault,
-        homeContextId: homeId,
-      }),
-    [model, graph, effectiveState, collapsedByDefault, homeId],
-  );
-
-  const layout = useMemo(
-    () => layoutProcess({ model, collapse, graph, profile, state: effectiveState }),
-    [model, collapse, graph, profile, effectiveState],
-  );
-
-  const nodeTypes = useMemo(() => makeNodeTypes(profile), [profile]);
-  const nodes = useMemo(() => layout.nodes.map(rfNode), [layout]);
-  const edges = useMemo(() => layout.edges.map(rfEdge), [layout]);
-
-  // occId kroku -> klucz refa (klik w nod przewija prozę do chipu).
-  const keyByOcc = useMemo(() => {
-    const m = new Map<string, string>();
-    for (const s of model.steps) if (s.ref) m.set(s.occId, s.ref.key);
-    return m;
-  }, [model]);
-
-  useEffect(() => {
-    if (!scrollToKey || !proseRef.current) return;
-    const el = proseRef.current.querySelector(
-      `[data-arc-key="${CSS.escape(scrollToKey)}"]`,
-    );
-    el?.scrollIntoView({ behavior: "smooth", block: "center" });
-    setScrollToKey(null);
-  }, [scrollToKey]);
-
-  const focusState = useMemo(
-    () => ({ focusNodeId, setFocusNodeId, scrollToKey, setScrollToKey }),
-    [focusNodeId, scrollToKey],
-  );
-
-  const viewStateActions = useMemo(
-    () => ({
-      state: effectiveState,
-      toggleGroup: (key: string, group: string) =>
-        updateState(toggleGroupState(effectiveState, key, group)),
-      toggleContext: (contextId: string) =>
-        updateState(
-          toggleContextState(effectiveState, contextId, collapsedByDefault),
-        ),
-    }),
-    [effectiveState, updateState, collapsedByDefault],
-  );
-
-  const processData = useMemo(() => ({ graph, profile }), [graph, profile]);
-
-  const selectionState = useMemo(
-    () => ({ selectedOcc, selectOcc: setSelectedOcc }),
-    [selectedOcc],
-  );
-
-  // Krok do drawera: wybrany occId szukamy najpierw wśród kroków po collapse
-  // (pseudo-kroki boxów), potem w oryginalnych (chip prozy członka boxa).
-  const selectedStep = useMemo(() => {
-    if (!selectedOcc) return null;
-    const group = collapse.groupByOcc.get(selectedOcc);
-    return (
-      collapse.steps.find((s) => s.occId === (group ?? selectedOcc)) ??
-      model.steps.find((s) => s.occId === selectedOcc) ??
-      null
-    );
-  }, [selectedOcc, collapse, model]);
-
+  const docKey = docId ?? title;
   return (
-    <ProcessDataContext.Provider value={processData}>
-      <FocusContext.Provider value={focusState}>
-        <SelectionContext.Provider value={selectionState}>
-        <ViewStateContext.Provider value={viewStateActions}>
+    <ProseInteractionRoot
+      mdx={mdx}
+      profile={profile}
+      graph={graph}
+      store={store}
+      docId={docId}
+      title={title}
+      defaultCollapsed={defaultCollapsed}
+      homeContextId={homeContextId}
+    >
+      {({ Prose, proseRef, model, collapse }) => (
+        <div
+          style={{
+            display: "grid",
+            gridTemplateColumns: "minmax(320px, 1fr) minmax(420px, 1.3fr)",
+            height: "100%",
+            minHeight: 0,
+            overflow: "hidden",
+          }}
+        >
           <div
+            ref={proseRef}
             style={{
-              display: "grid",
-              gridTemplateColumns: "minmax(320px, 1fr) minmax(420px, 1.3fr)",
-              height: "100%",
+              overflow: "auto",
               minHeight: 0,
-              overflow: "hidden",
+              padding: "20px 24px",
+              borderRight: `1px solid ${GLASS.border}`,
             }}
           >
-            {/* Proza */}
-            <div
-              ref={proseRef}
-              style={{
-                overflow: "auto",
-                minHeight: 0,
-                padding: "20px 24px",
-                borderRight: `1px solid ${GLASS.border}`,
-              }}
-            >
-              <MdxView key={docKey} mdx={mdx} onOccurrences={setOccurrences} />
-            </div>
-
-            {/* Diagram — sztywno wypełnia dostępną wysokość, bez scrolla strony */}
-            <div style={{ position: "relative", minHeight: 0, overflow: "hidden" }}>
-              <ReactFlow
-                key={docKey}
-                nodes={nodes}
-                edges={edges}
-                nodeTypes={nodeTypes}
-                nodesDraggable={false}
-                onNodeMouseEnter={(_, n) => {
-                  const step = (n.data as { step?: ProcessStep }).step;
-                  const id =
-                    step?.node?.id ??
-                    (n.data as { node?: { id: string } }).node?.id;
-                  if (id) setFocusNodeId(id);
-                }}
-                onNodeMouseLeave={() => setFocusNodeId(null)}
-                onNodeClick={(_, n) => {
-                  const k = keyByOcc.get(n.id);
-                  if (k) setScrollToKey(k);
-                  // Kroki (także boxy kontekstów) otwierają drawer.
-                  if (n.type === "step") setSelectedOcc(n.id);
-                }}
-                onPaneClick={() => setSelectedOcc(null)}
-                fitView
-                fitViewOptions={{ padding: 0.18 }}
-                minZoom={0.1}
-                proOptions={{ hideAttribution: true }}
-              >
-                <Background color="#dbeafe" gap={26} size={1.5} />
-                <Controls />
-                <MiniMap
-                  pannable
-                  zoomable
-                  nodeColor={(n) => {
-                    const step = (n.data as { step?: ProcessStep }).step;
-                    // Kolor z zadeklarowanego rodzaju — także dla TODO.
-                    const kind =
-                      step?.node?.kind ??
-                      step?.ref?.kind ??
-                      (n.data as { node?: { kind: string } }).node?.kind;
-                    return kind ? kindColor(profile, kind) : "#64748b";
-                  }}
-                  style={{
-                    background: "rgba(255,255,255,0.6)",
-                    border: `1px solid ${GLASS.border}`,
-                    borderRadius: 12,
-                  }}
-                />
-              </ReactFlow>
-
-              {/* Drawer szczegółów wybranego kroku. */}
-              {selectedStep ? (
-                <ProcessDrawer
-                  step={selectedStep}
-                  profile={profile}
-                  onClose={() => setSelectedOcc(null)}
-                  sourceProvider={sourceProvider}
-                />
-              ) : null}
-            </div>
+            {Prose}
           </div>
-        </ViewStateContext.Provider>
-        </SelectionContext.Provider>
-      </FocusContext.Provider>
-    </ProcessDataContext.Provider>
+          <ProcessFlowCanvas
+            model={model}
+            collapse={collapse}
+            docKey={docKey}
+            sourceProvider={sourceProvider}
+          />
+        </div>
+      )}
+    </ProseInteractionRoot>
   );
 }

package/src/react/process-flow-canvas.tsx

@@ -0,0 +1,179 @@
+/**
+ * `ProcessFlowCanvas` — procesowy renderer diagramu (ReactFlow + drawer).
+ *
+ * Slot diagramu dla `ProseInteractionRoot`: czyta graf/profil/focus/selekcję/
+ * stan z kontekstu, liczy layout (8 kierunków, track sizing) i renderuje
+ * ReactFlow. To JEDYNE miejsce importujące `@xyflow` — rdzeń prozy jest od
+ * niego wolny.
+ */
+
+import "@xyflow/react/dist/style.css";
+
+import {
+  Background,
+  Controls,
+  MarkerType,
+  MiniMap,
+  ReactFlow,
+  type Edge,
+  type Node,
+} from "@xyflow/react";
+import { useMemo } from "react";
+import type { CollapseResult } from "../model/collapse";
+import { layoutProcess, type DiagramEdge, type DiagramNode } from "../layout/layout";
+import { kindColor } from "../model/profile";
+import type { ProcessModel, ProcessStep } from "../model/types";
+import {
+  useFocus,
+  useProcessData,
+  useSelection,
+  useViewState,
+} from "../mdx/contexts";
+import { makeNodeTypes } from "./nodes";
+import { ProcessDrawer, type SourceProvider } from "./drawer";
+import { GLASS } from "./theme";
+
+function rfNode(n: DiagramNode): Node {
+  return {
+    id: n.id,
+    type: n.type,
+    position: { x: n.x, y: n.y },
+    width: n.w,
+    height: n.h,
+    data: n.data,
+    draggable: false,
+    selectable: n.type !== "context-group",
+    zIndex: n.type === "context-group" ? -1 : undefined,
+  };
+}
+
+function rfEdge(e: DiagramEdge): Edge {
+  return {
+    id: e.id,
+    source: e.source,
+    target: e.target,
+    label: e.label,
+    style: {
+      stroke: e.color,
+      strokeWidth: 1.5,
+      opacity: e.opacity ?? 0.75,
+      strokeDasharray: e.dashed ? "4 3" : undefined,
+    },
+    labelStyle: { fill: e.color, fontSize: 9, fontWeight: 600 },
+    labelBgStyle: { fill: "#fff", fillOpacity: 0.8 },
+    markerEnd: e.backbone
+      ? undefined
+      : { type: MarkerType.ArrowClosed, color: e.color },
+  };
+}
+
+export interface ProcessFlowCanvasProps {
+  model: ProcessModel;
+  collapse: CollapseResult;
+  /** Klucz remountu (docId) — świeży ReactFlow przy zmianie dokumentu. */
+  docKey?: string;
+  sourceProvider?: SourceProvider;
+}
+
+export function ProcessFlowCanvas({
+  model,
+  collapse,
+  docKey,
+  sourceProvider,
+}: ProcessFlowCanvasProps) {
+  const data = useProcessData();
+  const focus = useFocus();
+  const selection = useSelection();
+  const viewState = useViewState();
+  const profile = data!.profile;
+  const graph = data!.graph;
+
+  const layout = useMemo(
+    () =>
+      layoutProcess({
+        model,
+        collapse,
+        graph,
+        profile,
+        state: viewState.state,
+      }),
+    [model, collapse, graph, profile, viewState.state],
+  );
+
+  const nodeTypes = useMemo(() => makeNodeTypes(profile), [profile]);
+  const nodes = useMemo(() => layout.nodes.map(rfNode), [layout]);
+  const edges = useMemo(() => layout.edges.map(rfEdge), [layout]);
+
+  const keyByOcc = useMemo(() => {
+    const m = new Map<string, string>();
+    for (const s of model.steps) if (s.ref) m.set(s.occId, s.ref.key);
+    return m;
+  }, [model]);
+
+  const selectedStep = useMemo(() => {
+    if (!selection.selectedOcc) return null;
+    const group = collapse.groupByOcc.get(selection.selectedOcc);
+    return (
+      collapse.steps.find((s) => s.occId === (group ?? selection.selectedOcc)) ??
+      model.steps.find((s) => s.occId === selection.selectedOcc) ??
+      null
+    );
+  }, [selection.selectedOcc, collapse, model]);
+
+  return (
+    <div style={{ position: "relative", minHeight: 0, height: "100%", overflow: "hidden" }}>
+      <ReactFlow
+        key={docKey}
+        nodes={nodes}
+        edges={edges}
+        nodeTypes={nodeTypes}
+        nodesDraggable={false}
+        onNodeMouseEnter={(_, n) => {
+          const step = (n.data as { step?: ProcessStep }).step;
+          const id = step?.node?.id ?? (n.data as { node?: { id: string } }).node?.id;
+          if (id) focus.setFocusNodeId(id);
+        }}
+        onNodeMouseLeave={() => focus.setFocusNodeId(null)}
+        onNodeClick={(_, n) => {
+          const k = keyByOcc.get(n.id);
+          if (k) focus.setScrollToKey(k);
+          if (n.type === "step") selection.selectOcc(n.id);
+        }}
+        onPaneClick={() => selection.selectOcc(null)}
+        fitView
+        fitViewOptions={{ padding: 0.18 }}
+        minZoom={0.1}
+        proOptions={{ hideAttribution: true }}
+      >
+        <Background color="#dbeafe" gap={26} size={1.5} />
+        <Controls />
+        <MiniMap
+          pannable
+          zoomable
+          nodeColor={(n) => {
+            const step = (n.data as { step?: ProcessStep }).step;
+            const kind =
+              step?.node?.kind ??
+              step?.ref?.kind ??
+              (n.data as { node?: { kind: string } }).node?.kind;
+            return kind ? kindColor(profile, kind) : "#64748b";
+          }}
+          style={{
+            background: "rgba(255,255,255,0.6)",
+            border: `1px solid ${GLASS.border}`,
+            borderRadius: 12,
+          }}
+        />
+      </ReactFlow>
+
+      {selectedStep ? (
+        <ProcessDrawer
+          step={selectedStep}
+          profile={profile}
+          onClose={() => selection.selectOcc(null)}
+          sourceProvider={sourceProvider}
+        />
+      ) : null}
+    </div>
+  );
+}

package/src/react/prose-root.tsx

@@ -0,0 +1,233 @@
+/**
+ * `ProseInteractionRoot` — headless rdzeń interakcji „proza MDX + chipy".
+ *
+ * Trzyma CAŁY stan (wystąpienia, model, stan widoku, focus, selekcja) i
+ * providery (ProcessData/Focus/Selection/ViewState), renderuje prozę i
+ * udostępnia współdzielone API render-propem. NIE importuje ReactFlow — dzięki
+ * temu konsument prozy (np. dokumenty BMF z własnym canvasem grafu wiedzy) nie
+ * ciągnie `@xyflow`. Renderer diagramu jest SLOTEM: `ProcessDiagram` wpina
+ * `ProcessFlowCanvas`, dokumenty wpinają swój canvas — OBA czytają ten sam
+ * `FocusContext`/`SelectionContext`.
+ */
+
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentType,
+  type ReactNode,
+  type RefObject,
+} from "react";
+import { buildProcessModel } from "../model/build";
+import { collapseContexts, type CollapseResult } from "../model/collapse";
+import type { ProcessProfile } from "../model/profile";
+import {
+  EMPTY_GRAPH,
+  type Occurrence,
+  type ProcessGraph,
+  type ProcessModel,
+  type ResolvedRef,
+} from "../model/types";
+import {
+  initialViewState,
+  toggleContext as toggleContextState,
+  toggleGroup as toggleGroupState,
+  type ProcessViewState,
+} from "../state/view-state";
+import type { ProcessViewStore } from "../state/store";
+import { MdxView, parseProcessFrontmatter } from "../mdx/mdx-view";
+import {
+  FocusContext,
+  ProcessDataContext,
+  SelectionContext,
+  ViewStateContext,
+  type FocusState,
+  type SelectionState,
+  type ViewStateActions,
+} from "../mdx/contexts";
+
+/** API współdzielone przez rdzeń z rendererem diagramu (render-prop). */
+export interface ProseRootRenderApi {
+  /** Gotowy element prozy (MdxView w ArcRefsProvider). Osadź w kolumnie prozy. */
+  Prose: ReactNode;
+  /** Ref kolumny prozy — podepnij do kontenera, by działał scroll-do-chipu. */
+  proseRef: RefObject<HTMLDivElement | null>;
+  model: ProcessModel;
+  collapse: CollapseResult;
+  graph: ProcessGraph;
+  profile: ProcessProfile;
+  focus: FocusState;
+  selection: SelectionState;
+  viewState: ViewStateActions;
+  /** Domyślny tryb zwijania (z frontmatter/propsa). */
+  collapsedByDefault: boolean;
+}
+
+export interface ProseInteractionRootProps {
+  mdx: string;
+  profile: ProcessProfile;
+  graph?: ProcessGraph;
+  /** Extra/override komponenty MDX (Ref/Node/Rel/Metric/Formula konsumenta). */
+  components?: Record<string, ComponentType<Record<string, unknown>>>;
+  /** Most token→realId dla focusu (canvas grafu wiedzy). Brak = jak arc-map. */
+  resolveNodeId?: (ref: ResolvedRef) => string | null;
+  /** Podgląd zebranych wystąpień (np. do zbudowania overlayu grafu wiedzy). */
+  onOccurrences?: (occ: Occurrence[]) => void;
+  store?: ProcessViewStore;
+  docId?: string;
+  title?: string;
+  defaultCollapsed?: boolean;
+  homeContextId?: string;
+  children: (api: ProseRootRenderApi) => ReactNode;
+}
+
+export function ProseInteractionRoot({
+  mdx,
+  profile,
+  graph = EMPTY_GRAPH,
+  components,
+  resolveNodeId,
+  onOccurrences,
+  store,
+  docId,
+  title,
+  defaultCollapsed,
+  homeContextId,
+  children,
+}: ProseInteractionRootProps) {
+  const [occurrences, setOccurrences] = useState<Occurrence[]>([]);
+  const [viewState, setViewState] = useState<ProcessViewState | null>(null);
+  const [focusNodeId, setFocusNodeId] = useState<string | null>(null);
+  const [scrollToKey, setScrollToKey] = useState<string | null>(null);
+  const [selectedOcc, setSelectedOcc] = useState<string | null>(null);
+  const proseRef = useRef<HTMLDivElement | null>(null);
+
+  const frontmatter = useMemo(() => parseProcessFrontmatter(mdx), [mdx]);
+  const docKey = docId ?? title ?? frontmatter.title ?? mdx.slice(0, 48);
+  const collapsedByDefault =
+    defaultCollapsed ?? (frontmatter.collapse ?? "all") === "all";
+  const home = homeContextId ?? frontmatter.context;
+
+  useEffect(() => {
+    setOccurrences([]);
+    setViewState(null);
+    setSelectedOcc(null);
+  }, [mdx]);
+
+  const handleOccurrences = useCallback(
+    (occ: Occurrence[]) => {
+      setOccurrences(occ);
+      onOccurrences?.(occ);
+    },
+    [onOccurrences],
+  );
+
+  const model = useMemo(
+    () => buildProcessModel({ graph, profile, occurrences }),
+    [graph, profile, occurrences],
+  );
+
+  const homeId = useMemo(() => {
+    if (!home) return undefined;
+    const ctxs = graph.contexts ?? [];
+    return (ctxs.find((c) => c.id === home) ?? ctxs.find((c) => c.name === home))?.id;
+  }, [graph, home]);
+
+  const effectiveState = useMemo<ProcessViewState>(() => {
+    if (viewState) return viewState;
+    const stored = store?.load(docKey);
+    if (stored) return stored;
+    return initialViewState(model);
+  }, [viewState, store, docKey, model]);
+
+  const updateState = useCallback(
+    (next: ProcessViewState) => {
+      setViewState(next);
+      store?.save(docKey, next);
+    },
+    [store, docKey],
+  );
+
+  const collapse = useMemo(
+    () =>
+      collapseContexts(model, {
+        contexts: graph.contexts ?? [],
+        state: effectiveState,
+        defaultCollapsed: collapsedByDefault,
+        homeContextId: homeId,
+      }),
+    [model, graph, effectiveState, collapsedByDefault, homeId],
+  );
+
+  // Klik w nod przewija prozę do odpowiadającego chipu (data-arc-key).
+  useEffect(() => {
+    if (!scrollToKey || !proseRef.current) return;
+    const el = proseRef.current.querySelector(
+      `[data-arc-key="${CSS.escape(scrollToKey)}"]`,
+    );
+    el?.scrollIntoView({ behavior: "smooth", block: "center" });
+    setScrollToKey(null);
+  }, [scrollToKey]);
+
+  const focusState = useMemo<FocusState>(
+    () => ({ focusNodeId, setFocusNodeId, scrollToKey, setScrollToKey }),
+    [focusNodeId, scrollToKey],
+  );
+
+  const viewStateActions = useMemo<ViewStateActions>(
+    () => ({
+      state: effectiveState,
+      toggleGroup: (key, group) =>
+        updateState(toggleGroupState(effectiveState, key, group)),
+      toggleContext: (contextId) =>
+        updateState(
+          toggleContextState(effectiveState, contextId, collapsedByDefault),
+        ),
+    }),
+    [effectiveState, updateState, collapsedByDefault],
+  );
+
+  const processData = useMemo(
+    () => ({ graph, profile, resolveNodeId }),
+    [graph, profile, resolveNodeId],
+  );
+
+  const selectionState = useMemo<SelectionState>(
+    () => ({ selectedOcc, selectOcc: setSelectedOcc }),
+    [selectedOcc],
+  );
+
+  const Prose = (
+    <MdxView
+      key={docKey}
+      mdx={mdx}
+      components={components}
+      onOccurrences={handleOccurrences}
+    />
+  );
+
+  return (
+    <ProcessDataContext.Provider value={processData}>
+      <FocusContext.Provider value={focusState}>
+        <SelectionContext.Provider value={selectionState}>
+          <ViewStateContext.Provider value={viewStateActions}>
+            {children({
+              Prose,
+              proseRef,
+              model,
+              collapse,
+              graph,
+              profile,
+              focus: focusState,
+              selection: selectionState,
+              viewState: viewStateActions,
+              collapsedByDefault,
+            })}
+          </ViewStateContext.Provider>
+        </SelectionContext.Provider>
+      </FocusContext.Provider>
+    </ProcessDataContext.Provider>
+  );
+}

package/tests/build.test.ts

@@ -66,6 +66,26 @@ describe("buildProcessModel — parytet z buildUseCaseModel", () => {
     expect(m.steps[0].node).toBeUndefined();
   });
 
+  test("inline declare-node / relation occurrences are ignored (nie wchodzą w kroki)", () => {
+    const m = buildProcessModel({
+      graph,
+      profile: arcProfile,
+      occurrences: [
+        occ("o1", { command: "cmd" }),
+        {
+          type: "declare-node",
+          occId: "d1",
+          node: { id: "eph:x", kind: "ephemeral", label: "X" },
+        },
+        { type: "relation", occId: "r1", from: "a", to: "b", kind: "rel" },
+        occ("o2", { command: "cmd" }),
+      ],
+    });
+    // Tylko dwa kroki `<Arc>` — inline node/rel pomijane przez profil procesowy.
+    expect(m.steps.map((s) => s.occId)).toEqual(["o1", "o2"]);
+    expect(m.steps.map((s) => s.seq)).toEqual([1, 2]);
+  });
+
   test("forward attachments exclude visible; query dep becomes attachment", () => {
     const m = buildProcessModel({
       graph,

package/tests/layout.test.ts

@@ -269,6 +269,28 @@ describe("collapse kontekstów", () => {
     expect(rel[0].source.startsWith("grp:ctx_chat")).toBe(true);
   });
 
+  test("relacja prawo→lewo pominięta; lewo→prawo narysowana", () => {
+    // cmd queries v (semantyka "in"): strzałka biegnie v→cmd.
+    // Narracja cmd(depth0) → v(depth1): v jest NA PRAWO, strzałka wsteczna → skip.
+    const back = run([occ("o1", { command: "cmd" }), occ("o2", { view: "v" })]);
+    expect(back.layout.edges.filter((e) => e.id.startsWith("rel:"))).toHaveLength(0);
+    // Narracja v(depth0) → cmd(depth1): v na lewo, strzałka lewo→prawo → rysuj.
+    const fwd = run([occ("o1", { view: "v" }), occ("o2", { command: "cmd" })]);
+    expect(fwd.layout.edges.filter((e) => e.id.startsWith("rel:")).length).toBeGreaterThan(0);
+  });
+
+  test("relacja w tej samej kolumnie (Parallel) pominięta", () => {
+    // cmd mutates e (semantyka "out"): oba kroki w Parallel = ta sama kolumna.
+    const par = run([
+      { ...occ("o1", { command: "cmd" }), path: [{ type: "parallel", id: "P", laneIndex: 0 }] },
+      { ...occ("o2", { event: "e" }), path: [{ type: "parallel", id: "P", laneIndex: 1 }] },
+    ]);
+    const a = nodeById(par.layout.nodes, "o1");
+    const b = nodeById(par.layout.nodes, "o2");
+    expect(a.x).toBe(b.x); // ta sama kolumna
+    expect(par.layout.edges.filter((e) => e.id.startsWith("rel:"))).toHaveLength(0);
+  });
+
   test("initialViewState otwiera grupy z expand", () => {
     const o: StepOccurrence = { ...occ("o1", { command: "cmd" }), expand: ["mutates"] };
     const model = buildProcessModel({ graph, profile: arcProfile, occurrences: [o] });