@arcote.tech/arc-map 0.7.27

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@arcote.tech/arc-map",
+  "type": "module",
+  "version": "0.7.27",
+  "private": false,
+  "author": "Przemysław Krasiński [arcote.tech]",
+  "description": "Arc Context Map — interactive map of context spaces, elements, event-flow and React useScope usages (dev tool)",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./app": "./src/app/index.tsx"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "ts-morph": "^24.0.0",
+    "@xyflow/react": "^12.0.0",
+    "elkjs": "^0.9.3",
+    "@mdx-js/mdx": "^3.1.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.0"
+  },
+  "peerDependencies": {
+    "@arcote.tech/arc": "^0.7.27",
+    "@arcote.tech/platform": "^0.7.27",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "typescript": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "~5.9.3"
+  }
+}

package/src/app/arc.tsx

@@ -0,0 +1,92 @@
+/**
+ * `<Arc>` — inline reference to an Arc element inside use-case MDX prose.
+ *
+ * Renders a clickable chip and registers its resolved reference (in document
+ * order) so the scoped diagram knows which elements to show. Validates against
+ * the loaded map data: an unresolved reference gets a red border.
+ */
+
+import { useId, type ReactNode } from "react";
+import { resolveRef, type ArcRefProps } from "../refs";
+import { ELEMENT_COLOR } from "./theme";
+import { useArcRegister, useFocus, useMapData, useStructure } from "./contexts";
+
+type ArcProps = ArcRefProps & { children?: ReactNode };
+
+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 any))
+    return textOf((node as any).props?.children);
+  return "";
+}
+
+export function Arc(props: ArcProps) {
+  const { children, ...refProps } = props;
+  const id = useId();
+  const register = useArcRegister();
+  const map = useMapData();
+  const focus = useFocus();
+  const { path } = useStructure();
+
+  const ref = resolveRef(refProps as ArcRefProps);
+  const label = textOf(children);
+
+  // Register during render — idempotent (keyed by id), survives StrictMode.
+  register?.({ id, ref, label, props: refProps as ArcRefProps, path });
+
+  const resolved = !!ref && !!map && map.elements.some((e) => e.id === ref.nodeId);
+  const active = !!ref && focus.focusNodeId === ref.nodeId;
+  const color = resolved && ref ? mapColor(ref, map!) : "#e11d48";
+
+  return (
+    <span
+      data-arc-id={id}
+      data-arc-key={ref?.key ?? ""}
+      data-arc-node={ref?.nodeId ?? ""}
+      onMouseEnter={() => ref && resolved && focus.setFocusNodeId(ref.nodeId)}
+      onMouseLeave={() => focus.setFocusNodeId(null)}
+      title={
+        resolved
+          ? ref?.method
+            ? `${ref.nodeId}.${ref.method.name} (${ref.method.kind})`
+            : ref?.nodeId
+          : `Nieznana referencja: ${ref?.nodeId ?? JSON.stringify(refProps)}`
+      }
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        gap: 4,
+        padding: "1px 8px",
+        margin: "0 1px",
+        borderRadius: 8,
+        border: `1.5px solid ${resolved ? color : "#e11d48"}`,
+        background: resolved ? tint(color, 0.1) : "rgba(225,29,72,0.08)",
+        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: resolved ? color : "#e11d48" }} />
+      {label || ref?.nodeId || "?"}
+      {ref?.method ? <span style={{ color: "#6b5b86", fontWeight: 500 }}>·{ref.method.name}</span> : null}
+    </span>
+  );
+}
+
+function mapColor(ref: ReturnType<typeof resolveRef>, map: NonNullable<ReturnType<typeof useMapData>>): string {
+  const node = ref ? map.elements.find((e) => e.id === ref.nodeId) : undefined;
+  return (node && ELEMENT_COLOR[node.kind]) || "#7c3aed";
+}
+
+function tint(hex: string, alpha: number): string {
+  const h = hex.replace("#", "");
+  const r = parseInt(h.slice(0, 2), 16);
+  const g = parseInt(h.slice(2, 4), 16);
+  const b = parseInt(h.slice(4, 6), 16);
+  return `rgba(${r},${g},${b},${alpha})`;
+}

package/src/app/contexts.tsx

@@ -0,0 +1,72 @@
+/** Shared React contexts for the use-case view: map data, focus, ref collection. */
+
+import { createContext, useContext } from "react";
+import type { MapJson } from "../types";
+import type { ResolvedRef, ArcRefProps } from "../refs";
+
+/** The full graph data (from /api/map), used for validation + subgraph. */
+export const MapDataContext = createContext<MapJson | null>(null);
+export const useMapData = () => useContext(MapDataContext);
+
+/**
+ * Bidirectional highlight between `<Arc>` chips and diagram nodes. `focusNodeId`
+ * is the element id currently hovered (in prose or graph); `scrollKey` is the
+ * ref key a node click wants the prose to scroll to.
+ */
+export interface FocusState {
+  focusNodeId: string | null;
+  setFocusNodeId: (id: string | null) => void;
+  scrollToKey: string | null;
+  setScrollToKey: (key: string | null) => void;
+}
+export const FocusContext = createContext<FocusState>({
+  focusNodeId: null,
+  setFocusNodeId: () => {},
+  scrollToKey: null,
+  setScrollToKey: () => {},
+});
+export const useFocus = () => useContext(FocusContext);
+
+/** A structural wrapper segment on the path from MDX root to an `<Arc>`. */
+export interface PathSeg {
+  type: "parallel" | "branch" | "lane" | "step";
+  id: string;
+  /** Lane index of this child within a parallel/branch. */
+  laneIndex?: number;
+  title?: string;
+  /** Branch lanes are alternatives (XOR). */
+  alt?: boolean;
+}
+
+/** Structural context: the wrapper path the current subtree sits in. */
+export const StructureContext = createContext<{ path: PathSeg[] }>({ path: [] });
+export const useStructure = () => useContext(StructureContext);
+
+/** One collected `<Arc>` reference (in document order). */
+export interface ArcRegEntry {
+  /** Unique render-instance id (also the chip's DOM `data-arc-id`). */
+  id: string;
+  ref: ResolvedRef | null;
+  label: string;
+  props: ArcRefProps;
+  /** Structural path (parallel/branch/lane/step) the ref is nested in. */
+  path: PathSeg[];
+}
+
+/** Registration channel filled by `<Arc>` during render. */
+export const ArcRegisterContext = createContext<
+  ((entry: ArcRegEntry) => void) | null
+>(null);
+export const useArcRegister = () => useContext(ArcRegisterContext);
+
+/** Badge expand/collapse state for the use-case diagram (per step occurrence). */
+export interface ExpandState {
+  /** occId -> expanded relation kinds. */
+  expanded: Record<string, string[]>;
+  toggle: (occId: string, relKind: string) => void;
+}
+export const ExpandContext = createContext<ExpandState>({
+  expanded: {},
+  toggle: () => {},
+});
+export const useExpand = () => useContext(ExpandContext);

package/src/app/detail-panel.tsx

@@ -0,0 +1,164 @@
+/** Rich detail panel shown when an element or component node is selected. */
+
+import type { MapComponent, MapComponentEdge, MapElement, MapJson } from "../types";
+import { ELEMENT_COLOR, GLASS } from "./theme";
+
+interface Props {
+  map: MapJson;
+  selectedElement?: MapElement;
+  selectedComponent?: MapComponent;
+  onClose: () => void;
+}
+
+function Section({ title, children }: { title: string; children: React.ReactNode }) {
+  return (
+    <div style={{ marginBottom: 14 }}>
+      <div style={{ fontSize: 10.5, textTransform: "uppercase", letterSpacing: 0.6, color: GLASS.textMuted, marginBottom: 5, fontWeight: 700 }}>
+        {title}
+      </div>
+      {children}
+    </div>
+  );
+}
+
+function Json({ value }: { value: unknown }) {
+  if (value === undefined || value === null) return <em style={{ color: GLASS.textFaint }}>—</em>;
+  return (
+    <pre
+      style={{
+        margin: 0,
+        fontSize: 11,
+        lineHeight: 1.4,
+        color: "#3b2a55",
+        background: "rgba(124,58,237,0.06)",
+        border: `1px solid ${GLASS.border}`,
+        padding: 9,
+        borderRadius: 8,
+        overflow: "auto",
+        maxHeight: 220,
+      }}
+    >
+      {JSON.stringify(value, null, 2)}
+    </pre>
+  );
+}
+
+function ElementDetail({ el, map }: { el: MapElement; map: MapJson }) {
+  const color = ELEMENT_COLOR[el.kind] ?? ELEMENT_COLOR.unknown;
+  const consumers = map.componentEdges.filter((e) => e.target === el.id);
+  return (
+    <>
+      <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
+        <span style={{ color, fontSize: 12, textTransform: "uppercase" }}>{el.kind}</span>
+        {el.scope ? <span style={{ fontSize: 11, color: "#6b5b86" }}>scope: {el.scope}</span> : null}
+      </div>
+      <h2 style={{ margin: "4px 0 14px", fontSize: 18, color: "#2a173f" }}>{el.name}</h2>
+
+      {el.description ? <Section title="Description"><div style={{ fontSize: 12.5 }}>{el.description}</div></Section> : null}
+
+      <Section title="Space / Module">
+        <div style={{ fontSize: 12 }}>
+          {el.spaceId}
+          {el.moduleName ? <span style={{ color: "#6b5b86" }}> · {el.moduleName}</span> : null}
+        </div>
+      </Section>
+
+      {el.protections?.length ? (
+        <Section title="Protections">
+          <div style={{ fontSize: 12, color: "#b45309" }}>🔒 {el.protections.join(", ")}</div>
+        </Section>
+      ) : null}
+
+      {el.methods?.length ? (
+        <Section title="Methods">
+          <div style={{ display: "flex", flexWrap: "wrap", gap: 6 }}>
+            {el.methods.map((m) => (
+              <span key={`${m.kind}:${m.name}`} style={{ fontSize: 11, padding: "2px 7px", borderRadius: 5, background: "rgba(124,58,237,0.10)", color: "#3b2a55" }}>
+                {m.name}<span style={{ color: "#6b5b86" }}> · {m.kind}</span>
+              </span>
+            ))}
+          </div>
+        </Section>
+      ) : null}
+
+      {el.events?.length ? (
+        <Section title="Events"><div style={{ fontSize: 12 }}>{el.events.join(", ")}</div></Section>
+      ) : null}
+
+      {el.path ? <Section title="Path"><code style={{ fontSize: 12 }}>{el.path}</code></Section> : null}
+      {el.schema !== undefined ? <Section title="Schema"><Json value={el.schema} /></Section> : null}
+      {el.params !== undefined ? <Section title="Params"><Json value={el.params} /></Section> : null}
+      {el.payload !== undefined ? <Section title="Payload"><Json value={el.payload} /></Section> : null}
+      {el.results !== undefined ? <Section title="Results"><Json value={el.results} /></Section> : null}
+
+      {consumers.length ? (
+        <Section title={`React consumers (${consumers.length})`}>
+          {consumers.map((c: MapComponentEdge) => (
+            <div key={c.id} style={{ fontSize: 11.5, marginBottom: 3, color: "#3b2a55" }}>
+              <span style={{ color: c.usage === "query" ? "#2563eb" : "#d97706" }}>{c.usage}</span>{" "}
+              {c.source}
+              {c.methods.length ? <span style={{ color: "#6b5b86" }}> · {c.methods.join(", ")}</span> : null}
+            </div>
+          ))}
+        </Section>
+      ) : null}
+    </>
+  );
+}
+
+function ComponentDetail({ c, map }: { c: MapComponent; map: MapJson }) {
+  const uses = map.componentEdges.filter((e) => e.source === c.id);
+  return (
+    <>
+      <div style={{ fontSize: 12, color: "#7c3aed" }}>⚛ React component</div>
+      <h2 style={{ margin: "4px 0 14px", fontSize: 18, color: "#2a173f" }}>{c.name ?? c.file}</h2>
+      <Section title="File"><code style={{ fontSize: 11.5 }}>{c.file}</code></Section>
+      {c.package ? <Section title="Package"><div style={{ fontSize: 12 }}>{c.package}</div></Section> : null}
+      <Section title={`Uses (${uses.length})`}>
+        {uses.map((u) => (
+          <div key={u.id} style={{ fontSize: 11.5, marginBottom: 3, color: "#3b2a55" }}>
+            <span style={{ color: u.usage === "query" ? "#2563eb" : "#d97706" }}>{u.usage}</span>{" "}
+            <strong>{u.target}</strong>
+            {u.scope ? <span style={{ color: "#6b5b86" }}> · {u.scope}</span> : null}
+            {u.methods.length ? <span style={{ color: "#6b5b86" }}> · {u.methods.join(", ")}</span> : null}
+            {u.line ? <span style={{ color: "#9b8cb5" }}> :{u.line}</span> : null}
+          </div>
+        ))}
+      </Section>
+    </>
+  );
+}
+
+export function DetailPanel({ map, selectedElement, selectedComponent, onClose }: Props) {
+  if (!selectedElement && !selectedComponent) return null;
+  return (
+    <div
+      style={{
+        position: "absolute",
+        top: 12,
+        right: 12,
+        bottom: 12,
+        width: 360,
+        background: GLASS.cardStrong,
+        backdropFilter: GLASS.blur,
+        WebkitBackdropFilter: GLASS.blur,
+        border: `1px solid ${GLASS.border}`,
+        borderRadius: 18,
+        padding: 18,
+        overflow: "auto",
+        zIndex: 10,
+        boxShadow: GLASS.shadowStrong,
+        color: GLASS.text,
+      }}
+    >
+      <button
+        onClick={onClose}
+        style={{ float: "right", background: "transparent", border: "none", color: GLASS.textMuted, fontSize: 18, cursor: "pointer" }}
+      >
+        ×
+      </button>
+      {selectedElement ? <ElementDetail el={selectedElement} map={map} /> : null}
+      {selectedComponent ? <ComponentDetail c={selectedComponent} map={map} /> : null}
+    </div>
+  );
+}

package/src/app/index.tsx

@@ -0,0 +1,107 @@
+/** Browser entry — fetches /api/map + /api/use-cases, renders the mode switch. */
+
+import "@xyflow/react/dist/style.css";
+import { StrictMode, useEffect, useState } from "react";
+import { createRoot } from "react-dom/client";
+import type { MapJson, UseCaseEntry } from "../types";
+import { MapView } from "./map-view";
+import { UseCaseView } from "./usecase-view";
+import { GLASS } from "./theme";
+
+type Mode = "use-cases" | "explore";
+
+function ModeSwitch({ mode, setMode }: { mode: Mode; setMode: (m: Mode) => void }) {
+  const Btn = ({ id, label }: { id: Mode; label: string }) => (
+    <button
+      onClick={() => setMode(id)}
+      style={{
+        padding: "6px 14px",
+        borderRadius: 9,
+        border: "none",
+        cursor: "pointer",
+        fontSize: 13,
+        fontWeight: 600,
+        color: mode === id ? "#fff" : GLASS.text,
+        background: mode === id ? "#7c3aed" : "transparent",
+      }}
+    >
+      {label}
+    </button>
+  );
+  return (
+    <div
+      style={{
+        display: "flex",
+        gap: 4,
+        alignItems: "center",
+        padding: "8px 12px",
+        borderBottom: `1px solid ${GLASS.border}`,
+        background: GLASS.card,
+        backdropFilter: GLASS.blur,
+      }}
+    >
+      <span style={{ fontWeight: 800, color: GLASS.text, marginRight: 10 }}>Arc Map</span>
+      <Btn id="use-cases" label="Use cases" />
+      <Btn id="explore" label="Explore all" />
+    </div>
+  );
+}
+
+function App() {
+  const [map, setMap] = useState<MapJson | null>(null);
+  const [useCases, setUseCases] = useState<UseCaseEntry[]>([]);
+  const [error, setError] = useState<string | null>(null);
+  const [mode, setMode] = useState<Mode>("use-cases");
+
+  const load = () => {
+    fetch("/api/map")
+      .then((r) => r.json())
+      .then((data) => (data?.error ? setError(data.error) : (setMap(data), setError(null))))
+      .catch((e) => setError(String(e)));
+    fetch("/api/use-cases")
+      .then((r) => r.json())
+      .then((d) => setUseCases(d.useCases ?? []))
+      .catch(() => setUseCases([]));
+  };
+
+  useEffect(() => {
+    load();
+    const es = new EventSource("/api/reload-stream");
+    es.onmessage = (ev) => {
+      if (ev.data && ev.data !== "connected") load();
+    };
+    return () => es.close();
+  }, []);
+
+  if (error) {
+    return (
+      <div style={{ padding: 24, color: "#be123c", fontFamily: "ui-monospace, monospace" }}>
+        <strong>arc-map error:</strong>
+        <pre>{error}</pre>
+      </div>
+    );
+  }
+  if (!map) return <div style={{ padding: 24, color: "#6b5b86" }}>Ładuję kontekst…</div>;
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", height: "100%" }}>
+      <ModeSwitch mode={mode} setMode={setMode} />
+      <div style={{ flex: 1, minHeight: 0 }}>
+        {mode === "use-cases" ? (
+          <UseCaseView map={map} useCases={useCases} />
+        ) : (
+          <MapView map={map} />
+        )}
+      </div>
+    </div>
+  );
+}
+
+const root = document.getElementById("root");
+if (root) {
+  createRoot(root).render(
+    <StrictMode>
+      <App />
+    </StrictMode>,
+  );
+}