@arach/arc 0.4.5 → 0.6.0

package/docs/llm.txt

@@ -0,0 +1,208 @@
+# Arc - LLM Context File
+
+> Diagrams as code — visual editor + React renderer for architecture diagrams
+> Source: https://github.com/arach/arc
+> Docs: https://arc.arach.dev/docs
+> Contributor guide: CLAUDE.md (repo root — read before editor changes)
+
+## Quick Facts
+
+- **What**: Drag-and-drop studio + `<ArcDiagram />` player for typed architecture diagrams
+- **Output**: JSON / TypeScript configs (not images) — diffable, versionable
+- **Stack**: React 19, Vite 7, TailwindCSS 4, Hudson shell (editor chrome)
+- **Package manager**: bun (`bun install`, `bun run dev`)
+- **MCP**: `arc-mcp` bin — see `docs/agent/mcp.agent.md`
+
+## Which Package?
+
+| Goal | Package / path |
+|------|----------------|
+| Render a 2D diagram in React | `@arach/arc` or `@arach/arc-viewer` |
+| Mermaid sequence diagrams | `@arach/arc-viewer` (`ArcMermaidPlayer`) |
+| Isometric / YAML tier diagrams | `@arach/arc-iso` |
+| Full visual studio | Clone repo → `bun run dev` → `/editor` |
+| Contribute to editor | This repo — see CLAUDE.md |
+
+`@arach/arc` is the main publish surface (player + editor components + utilities).
+`@arach/arc-viewer` is a slimmer install when you only need read-only rendering.
+
+## Commands
+
+```bash
+bun install
+bun run dev          # → http://localhost:5188/editor
+bun run build
+bun run lint
+bun run typecheck
+```
+
+## Canonical Diagram Schema
+
+Source of truth: `src/types/diagram.ts`
+
+```typescript
+interface ArcDiagramData {
+  id?: string
+  layout: { width: number; height: number }
+  layoutHints?: LayoutHints          // auto-layout inside groups
+  nodes: Record<string, { x: number; y: number; size: 'xs' | 's' | 'm' | 'l' }>
+  nodeData: Record<string, {
+    icon: string                     // Lucide name as string
+    name: string
+    subtitle?: string
+    description?: string
+    color: DiagramColor
+    shape?: NodeShape                // per-node silhouette override
+  }>
+  connectors: Array<{
+    from: string; to: string
+    fromAnchor: AnchorPosition; toAnchor: AnchorPosition
+    style: string
+    curve?: 'natural' | 'step'
+  }>
+  connectorStyles: Record<string, {
+    color: DiagramColor
+    strokeWidth: number
+    label?: string
+    dashed?: boolean
+  }>
+  groups?: GroupShape[]
+  focusTargets?: Record<string, FocusTarget>
+}
+```
+
+**Node sizes** (`src/utils/constants.ts` NODE_SIZES):
+- `xs` 80×36 · `s` 110×48 · `m` 160×75 · `l` 220×90
+
+**Do not use** legacy Talkie sizes (`large`, `normal`, `small`) — see HANDOFF.md.
+
+**`_meta`** (saved with files, round-trips through sessions):
+`themeId`, `colorMode`, `viewMode`, `isoStyle`, `viewport`
+
+Validate external JSON with `validateDiagramShape()` in `src/utils/diagramValidation.ts`.
+
+## Minimal Example
+
+```tsx
+import { ArcDiagram } from '@arach/arc'
+import type { ArcDiagramData } from '@arach/arc'
+
+const diagram: ArcDiagramData = {
+  layout: { width: 600, height: 300 },
+  nodes: {
+    frontend: { x: 50, y: 100, size: 'm' },
+    backend: { x: 250, y: 100, size: 'm' },
+  },
+  nodeData: {
+    frontend: { icon: 'Monitor', name: 'Frontend', color: 'violet' },
+    backend: { icon: 'Server', name: 'Backend', color: 'emerald' },
+  },
+  connectors: [
+    { from: 'frontend', to: 'backend', fromAnchor: 'right', toAnchor: 'left', style: 'api' },
+  ],
+  connectorStyles: {
+    api: { color: 'violet', strokeWidth: 2, label: 'REST' },
+  },
+}
+
+<ArcDiagram data={diagram} mode="light" theme="default" defaultZoom="fit" />
+```
+
+## Auto-layout (prefer over hand-positioning)
+
+```typescript
+import { autoLayout } from '@arach/arc'
+
+const laidOut = autoLayout({
+  nodeData: { /* ... */ },
+  connectors: [/* omit anchors — inferred */],
+  connectorStyles: { /* ... */ },
+})
+```
+
+See `docs/group-layout.md` for `layoutHints` / group frames.
+
+## Project Structure (contributors)
+
+```
+src/
+├── main.tsx / App.tsx              # Routes: /, /editor, /player, /showcase, /docs
+├── apps/
+│   ├── arc-editor/                 # Hudson shell wrapper (canonical editor UX)
+│   └── arc-showcase/               # Player harness with inspector controls
+├── components/
+│   ├── ArcDiagram.tsx              # 2D player (also exported as @arach/arc)
+│   ├── editor/                     # Canvas, reducer, nodes, connectors
+│   │   ├── editorReducer.ts        # All state transitions
+│   │   ├── DiagramCanvas.tsx
+│   │   ├── DiagramEditor.tsx       # Legacy layout (canvas still lives here)
+│   │   └── EditorProvider.tsx
+│   ├── chrome/                     # Settings rail, markup pane (CodeMirror)
+│   └── diagrams/*.diagram.ts       # Canonical examples — copy these
+├── types/diagram.ts                # Public diagram schema
+├── utils/                          # themes, validation, export, autoLayout, icons
+└── iso/                            # Isometric renderer
+
+packages/
+├── viewer/                         # @arach/arc-viewer (+ Mermaid)
+└── iso/                            # @arach/arc-iso
+```
+
+**Editor entry flow**: `/editor` → `createArcEditorApp()` (Hudson) → `ArcEditorContent` → `DiagramEditor` / `DiagramCanvas`.
+Shell chrome (nav, rail, inspector, markup pane) is Hudson + `src/components/chrome/`.
+Canvas logic and reducer are in `src/components/editor/`.
+
+## State Shape
+
+```typescript
+{
+  diagram: { layout, grid, nodes, nodeData, connectors, connectorStyles, groups, images, exportZone },
+  editor: { selectedNodeIds, selectedConnectorIndex, mode, pendingConnector, viewMode, isoStyle, themeId, colorMode, ... },
+  meta: { filename, isDirty, lastSaved, diagramMeta },
+  history: { past, future }   // capped at 50
+}
+```
+
+Reducer actions: see `docs/agent/editor-actions.agent.md`
+
+## Themes
+
+Diagram themes (8): `default`, `warm`, `cool`, `mono`, `engineering`, `workbench`, `tactical`, `command`
+Chrome skins (shell only): `console`, `graphite`, `amber`, `viridian`, `paper`
+
+## Visual Verification
+
+```bash
+bun run dev
+# Open http://localhost:5188/editor/:sessionId
+# Or http://localhost:5188/showcase?doc=platform
+
+# Dev-only PNG capture:
+curl "http://localhost:5188/capture/my-session" > out.png
+```
+
+## Agent Artifacts
+
+| File | Purpose |
+|------|---------|
+| CLAUDE.md | Full contributor context (best doc in repo) |
+| docs/llm.txt | This file — dense agent briefing |
+| docs/agent/*.agent.md | Per-topic agent context |
+| skills/arc-diagrams/SKILL.md | Diagram generation skill |
+| docs/prompts/*.md | Task prompt templates |
+| public/llms.txt | Served at /llms.txt (summary) |
+
+## MCP
+
+`arc-mcp` bin on `@arach/arc` (`bun run mcp` in dev, `bun run build:mcp` for publish).
+Tools: validate_diagram, auto_layout, render_ascii, diagram_to_typescript, editor_handoff.
+See docs/agent/mcp.agent.md for coverage gaps (SVG/PNG/Mermaid stay elsewhere).
+
+## Critical Rules
+
+1. Diagrams are JSON data — keep them declarative and deterministic
+2. Node sizes are `xs` | `s` | `m` | `l` only
+3. Icons are Lucide **string names**, registered in `src/utils/iconRegistry.ts`
+4. State is immutable — reducer returns new objects; history on diagram mutations
+5. `diagram/replace` (markup pane) pushes history; `diagram/load` does not
+6. Read CLAUDE.md before touching chrome tokens, markup pane, or canvas overlays

package/lib/MarkupPanel-CroO7O49.js

@@ -0,0 +1,182 @@
+import { jsxs as j, jsx as a } from "react/jsx-runtime";
+import { useState as f, useRef as N, useMemo as Z, useEffect as C, useCallback as h } from "react";
+import { C as q, a as B, X as G, b as Q, v as V } from "./index-CbEv7M-m.js";
+const L = "arc-markup-width", u = 460, D = 280, ee = 0.68, P = 24;
+function T() {
+  return typeof window > "u" ? u : Math.max(D, Math.round(window.innerWidth * ee));
+}
+const M = (r) => Math.min(Math.max(r, D), T());
+function te() {
+  if (typeof window > "u") return u;
+  try {
+    const r = Number(window.localStorage.getItem(L));
+    return Number.isFinite(r) && r >= D ? M(r) : u;
+  } catch {
+    return u;
+  }
+}
+function I(r) {
+  try {
+    window.localStorage.setItem(L, String(r));
+  } catch {
+  }
+}
+function re(r, o = "diagram") {
+  const w = JSON.stringify(r, null, 2).replace(/"([^"]+)":/g, "$1:").replace(/"/g, "'");
+  return `import type { ArcDiagramData } from '@arach/arc'
+
+const ${o}: ArcDiagramData = ${w}
+
+export default ${o}
+`;
+}
+function oe({ title: r, data: o, onApply: w, onClose: S }) {
+  const [n, A] = f("json"), [W, $] = f(!1), [g, s] = f({ kind: "clean" }), [J, k] = f(null), i = N(null), d = N(null), m = N(null), [c, y] = f(te), l = N(null), b = Z(
+    () => n === "ts" ? re(o) : JSON.stringify(o, null, 2),
+    [n, o]
+  ), E = n === "json" && !!w, R = J ?? b;
+  C(() => {
+    if (m.current !== null && m.current === b) {
+      m.current = null;
+      return;
+    }
+    m.current = null, k(null), s({ kind: "clean" });
+  }, [b]), C(() => {
+    const e = (t) => {
+      t.key !== "Escape" || t.target?.closest?.(".cm-editor") || S();
+    };
+    return document.addEventListener("keydown", e), () => document.removeEventListener("keydown", e);
+  }, [S]), C(() => () => {
+    i.current && window.clearTimeout(i.current), d.current && window.clearTimeout(d.current);
+  }, []), C(() => {
+    const e = () => y((t) => t > T() ? T() : t);
+    return window.addEventListener("resize", e), () => window.removeEventListener("resize", e);
+  }, []);
+  const X = h((e) => {
+    e.preventDefault(), e.target.setPointerCapture(e.pointerId), l.current = { startX: e.clientX, startWidth: c };
+  }, [c]), F = h((e) => {
+    l.current && y(M(l.current.startWidth + (e.clientX - l.current.startX)));
+  }, []), x = h((e) => {
+    l.current && (l.current = null, e.target.releasePointerCapture?.(e.pointerId), I(c));
+  }, [c]), _ = h(() => {
+    y(u), I(u);
+  }, []), K = h((e) => {
+    const t = e.key === "ArrowLeft" ? -P : e.key === "ArrowRight" ? P : 0;
+    t && (e.preventDefault(), y((p) => {
+      const v = M(p + t);
+      return I(v), v;
+    }));
+  }, []), H = (e) => {
+    if (e === b) {
+      i.current && window.clearTimeout(i.current), k(null);
+      return;
+    }
+    k(e), E && (i.current && window.clearTimeout(i.current), i.current = window.setTimeout(() => {
+      let t;
+      try {
+        t = JSON.parse(e);
+      } catch (v) {
+        s({ kind: "error", message: v.message.replace(/^JSON\.parse: /, "") });
+        return;
+      }
+      const p = V(t);
+      if (p) {
+        s({ kind: "error", message: p });
+        return;
+      }
+      m.current = JSON.stringify(t, null, 2), w?.(t), s({ kind: "applied" });
+    }, 400));
+  }, z = (e) => {
+    e !== n && (i.current && window.clearTimeout(i.current), k(null), s({ kind: "clean" }), A(e));
+  }, U = async () => {
+    try {
+      await navigator.clipboard.writeText(R), $(!0), d.current && window.clearTimeout(d.current), d.current = window.setTimeout(() => $(!1), 1600);
+    } catch {
+      s({ kind: "error", message: "Clipboard unavailable — select the text and copy" });
+    }
+  }, O = R.split(`
+`).length, Y = g.kind === "error" ? `⚠ ${g.message}` : g.kind === "applied" ? `${O} lines · applied to canvas` : `${O} lines · ${n === "ts" ? "read-only export" : E ? "edit to update the diagram" : "diagram JSON"}`;
+  return /* @__PURE__ */ j("aside", { className: "arc-markup-pane", style: { width: c }, "aria-label": "Diagram markup", children: [
+    /* @__PURE__ */ j("div", { className: "arc-markup-head", children: [
+      /* @__PURE__ */ a("span", { className: "arc-markup-title", title: r, children: r }),
+      /* @__PURE__ */ j("div", { className: "arc-markup-formats", role: "group", "aria-label": "Markup format", children: [
+        /* @__PURE__ */ a(
+          "button",
+          {
+            type: "button",
+            className: `arc-settings-segment${n === "json" ? " is-active" : ""}`,
+            "aria-pressed": n === "json",
+            onClick: () => z("json"),
+            children: ".json"
+          }
+        ),
+        /* @__PURE__ */ a(
+          "button",
+          {
+            type: "button",
+            className: `arc-settings-segment${n === "ts" ? " is-active" : ""}`,
+            "aria-pressed": n === "ts",
+            onClick: () => z("ts"),
+            children: ".ts"
+          }
+        )
+      ] }),
+      /* @__PURE__ */ a(
+        "button",
+        {
+          type: "button",
+          className: "arc-editor-btn",
+          onClick: U,
+          title: W ? "Copied" : "Copy markup",
+          "aria-label": "Copy markup",
+          children: W ? /* @__PURE__ */ a(q, {}) : /* @__PURE__ */ a(B, {})
+        }
+      ),
+      /* @__PURE__ */ a("button", { type: "button", className: "arc-editor-btn", onClick: S, title: "Close", "aria-label": "Close markup", children: /* @__PURE__ */ a(G, {}) })
+    ] }),
+    /* @__PURE__ */ a("div", { className: "arc-markup-source", children: /* @__PURE__ */ a(
+      Q,
+      {
+        code: R,
+        language: n === "ts" ? "typescript" : "json",
+        filename: n === "ts" ? "diagram.ts" : "diagram.json",
+        readOnly: !E,
+        showLineNumbers: !0,
+        onChange: H
+      },
+      n
+    ) }),
+    /* @__PURE__ */ a(
+      "div",
+      {
+        className: `arc-markup-foot${g.kind === "error" ? " is-error" : ""}`,
+        role: "status",
+        "aria-live": "polite",
+        children: Y
+      }
+    ),
+    /* @__PURE__ */ a(
+      "div",
+      {
+        className: "arc-markup-resizer",
+        role: "separator",
+        tabIndex: 0,
+        "aria-orientation": "vertical",
+        "aria-label": "Resize markup pane",
+        "aria-valuenow": c,
+        "aria-valuemin": D,
+        "aria-valuemax": T(),
+        onPointerDown: X,
+        onPointerMove: F,
+        onPointerUp: x,
+        onPointerCancel: x,
+        onDoubleClick: _,
+        onKeyDown: K
+      }
+    )
+  ] });
+}
+export {
+  oe as default,
+  re as toTsSource
+};