@arach/arc 0.5.0 → 0.7.0

package/lib/index.d.ts

@@ -22,7 +22,21 @@ export declare interface ArcConnectorStyle {
     dashed?: boolean;
 }
 
-export declare function ArcDiagram({ data, className, interactive, mode, theme, label, labelPosition, defaultZoom, zoomLevels, showArcToggle, showAutoLayout, showControls, showMinimap, showLegend, showFocusStory, frame, hoverEffects, onNodeHover, titleBlock, maxFitZoom, }: ArcDiagramProps): JSX.Element;
+export declare function ArcDiagram({ data, className, interactive, mode, theme, label, labelPosition, defaultZoom, zoomLevels, showArcToggle, showAutoLayout, showControls, showMinimap, showLegend, showFocusStory, frame, hoverEffects, onNodeHover, titleBlock, maxFitZoom, defaultViewMode, defaultIsoStyle, }: ArcDiagramProps): JSX.Element;
+
+declare interface ArcDiagram_2 {
+    layout: DiagramLayout_2;
+    grid: GridConfig;
+    layoutHints?: LayoutHints_2;
+    nodes: Record<string, NodePosition_2>;
+    nodeData: Record<string, NodeData>;
+    connectors: Connector[];
+    connectorStyles: Record<string, ConnectorStyle_2>;
+    groups?: GroupShape_2[];
+    focusTargets?: Record<string, FocusTarget_2>;
+    images?: DiagramImage[];
+    exportZone?: ExportZone | null;
+}
 
 export declare interface ArcDiagramData {
     id?: string;
@@ -86,6 +100,10 @@ declare interface ArcDiagramProps {
     onNodeHover?: (nodeId: string | null) => void;
     /** Override the engineering title-block fields (shown when the theme opts in). */
     titleBlock?: TitleBlockInfo;
+    /** Render the diagram in isometric projection. Default: '2d' */
+    defaultViewMode?: ViewMode_2;
+    /** Isometric render style — 'solid' | 'blueprint' | 'cyanotype'. Default: 'solid' */
+    defaultIsoStyle?: IsoStyleId;
 }
 
 declare interface ArcDiagramProps_2 {
@@ -108,6 +126,8 @@ export declare interface ArcNodeData {
     subtitle?: string;
     description?: string;
     color: DiagramColor;
+    /** Per-node silhouette. Omit to follow the theme's own node shape. */
+    shape?: NodeShape;
 }
 
 export declare interface ArcNodePosition {
@@ -282,7 +302,7 @@ export declare function deleteDiagramSession(id: string): void;
 /** Derive a URL-safe session ID from a diagram's source path or ID */
 export declare function deriveSessionId(source: string): string;
 
-export declare function DiagramCanvas({ onViewportChange, embedConfig, zoomConfig, themeOverride, isDark }: DiagramCanvasProps): JSX.Element;
+export declare function DiagramCanvas({ onViewportChange, embedConfig, zoomConfig, surface, themeOverride, isDark }: DiagramCanvasProps): JSX.Element;
 
 declare interface DiagramCanvasProps {
     onViewportChange?: (bounds: {
@@ -293,6 +313,10 @@ declare interface DiagramCanvasProps {
     }) => void;
     embedConfig?: EmbedConfig;
     zoomConfig?: ZoomConfig;
+    /** Workspace backdrop: 'theme' paints the diagram theme's container (embeds,
+     *  where the frame is part of the artifact), 'chrome' paints the app canvas
+     *  so the editor's infinite surface matches the shell skin. */
+    surface?: 'theme' | 'chrome';
     /** Override canvas background with an Arc theme. */
     themeOverride?: string;
     isDark?: boolean;
@@ -368,6 +392,17 @@ export declare function DiagramEditor({ initialData, themeId, colorMode, session
     initialDiagramMeta?: Record<string, any>;
 }): JSX.Element;
 
+declare interface DiagramImage {
+    id: string;
+    src: string;
+    name: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    opacity: number;
+}
+
 export declare interface DiagramLayout {
     width: number;
     height: number;
@@ -459,6 +494,13 @@ export declare interface EmbedConfig {
     showGrid?: boolean;
 }
 
+declare interface ExportZone {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
 export declare interface FocusConnectorRef {
     from: string;
     to: string;
@@ -511,6 +553,14 @@ export declare function getThemeList(): {
     description: string;
 }[];
 
+declare interface GridConfig {
+    enabled: boolean;
+    size: number;
+    color: string;
+    opacity: number;
+    type: 'dots' | 'lines';
+}
+
 export declare type GroupLayoutDirection = 'horizontal' | 'vertical';
 
 declare type GroupLayoutDirection_2 = 'horizontal' | 'vertical';
@@ -628,6 +678,8 @@ declare const initialState: {
     };
 };
 
+export declare function isDiagramShape(value: unknown): boolean;
+
 /** Preset HSL palettes matching Arc's diagram colors. */
 export declare const ISO_COLORS: {
     violet: IsoColorDef;
@@ -748,6 +800,8 @@ declare interface NodeData {
     subtitle?: string;
     description?: string;
     color: DiagramColor_2;
+    /** Per-node silhouette. Omit to follow the theme's own node shape. */
+    shape?: NodeShape;
 }
 
 export declare interface NodeLayoutHint {
@@ -783,11 +837,13 @@ declare interface NodePosition_2 {
     size: NodeSize_2;
 }
 
+declare type NodeShape = 'rounded' | 'square' | 'chamfer' | 'notch' | 'pill';
+
 export declare type NodeSize = 'xs' | 's' | 'm' | 'l';
 
 declare type NodeSize_2 = 'xs' | 's' | 'm' | 'l';
 
-declare type NodeSize_3 = 'large' | 'normal' | 'small';
+declare type NodeSize_3 = 'xs' | 's' | 'm' | 'l';
 
 /**
  * Parse YAML config into DiagramConfig
@@ -936,6 +992,10 @@ declare interface TitleBlockInfo {
     sheet?: string;
 }
 
+export declare function toExportFormat(diagram: ArcDiagram_2): ArcDiagramData_2;
+
+export declare function toTypeScriptSource(diagram: ArcDiagram_2, name?: string): string;
+
 export declare function useColorMode(): string;
 
 export declare function useDiagram(): {
@@ -1005,8 +1065,13 @@ export declare function useThemeId(): string;
 
 export declare function useViewMode(): string;
 
+/** Human-readable reason this is not a diagram, or null if it is. */
+export declare function validateDiagramShape(value: unknown): string | null;
+
 export declare type ViewMode = '2d' | 'isometric';
 
+declare type ViewMode_2 = '2d' | 'isometric';
+
 declare interface ZoomConfig {
     defaultZoom?: number | 'fit';
     zoomLevels?: number[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arach/arc",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "type": "module",
   "packageManager": "bun@1.3.11",
   "workspaces": [
@@ -11,7 +11,14 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/arach/arc.git"
+    "url": "git+https://github.com/arach/arc.git"
+  },
+  "homepage": "https://github.com/arach/arc#readme",
+  "bugs": {
+    "url": "https://github.com/arach/arc/issues"
+  },
+  "engines": {
+    "node": ">=18"
   },
   "publishConfig": {
     "access": "public",
@@ -27,13 +34,18 @@
     "isometric"
   ],
   "bin": {
-    "arc-ascii": "./bin/arc-ascii.mjs"
+    "arc-ascii": "./bin/arc-ascii.mjs",
+    "arc-mcp": "./bin/arc-mcp.mjs"
   },
   "files": [
     "lib/*.js",
     "lib/*.d.ts",
     "lib/*.css",
-    "bin/arc-ascii.mjs"
+    "bin/arc-ascii.mjs",
+    "bin/arc-mcp.mjs",
+    "docs/llm.txt",
+    "skills/arc-diagrams/SKILL.md",
+    "src/types/diagram.ts"
   ],
   "main": "./lib/arc.umd.js",
   "module": "./lib/arc.es.js",
@@ -50,13 +62,16 @@
     "dev": "vite",
     "build": "tsc && vite build && node scripts/generate-docs-html.js",
     "build:lib": "vite build --config vite.config.lib.js",
+    "build:mcp": "bun scripts/build-arc-mcp.mjs",
+    "mcp": "bun scripts/mcp/server.ts",
+    "mcp:http": "bun scripts/mcp/http-server.ts",
     "build:iso": "vite build --config vite.config.iso.js && vite build --config vite.config.iso-slim.js",
     "lint": "eslint .",
     "typecheck": "tsc --noEmit",
     "preview": "vite preview",
     "generate-og": "node scripts/generate-og.js",
     "check:dist": "attw --pack . --ignore-rules cjs-resolves-to-esm unexpected-module-syntax && publint && node scripts/check-packlist.mjs",
-    "prepublishOnly": "bun run build:lib && bun run check:dist"
+    "prepublishOnly": "bun run build:lib && bun run build:mcp && bun run check:dist"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
@@ -66,13 +81,24 @@
     "@arach/dewey": "^0.2.0",
     "@arethetypeswrong/cli": "^0.18.4",
     "@base-ui/react": "^1.0.0",
+    "@codemirror/commands": "^6.10.4",
+    "@codemirror/lang-css": "^6.3.1",
+    "@codemirror/lang-html": "^6.4.12",
+    "@codemirror/lang-javascript": "^6.2.5",
+    "@codemirror/lang-json": "^6.0.2",
+    "@codemirror/lang-markdown": "^6.5.2",
+    "@codemirror/language": "^6.12.4",
+    "@codemirror/state": "^6.7.1",
+    "@codemirror/view": "^6.43.8",
     "@eslint/js": "^9.39.1",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "@tailwindcss/vite": "^4.1.18",
     "@types/js-yaml": "^4.0.9",
     "@types/react": "^19.2.5",
     "@types/react-dom": "^19.2.3",
     "@types/three": "^0.182.0",
     "@vitejs/plugin-react": "^5.1.1",
+    "codemirror": "^6.0.2",
     "eslint": "^9.39.1",
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.4.24",
@@ -91,7 +117,9 @@
     "tailwindcss": "^4.1.18",
     "three": "^0.182.0",
     "typescript": "^5.9.3",
+    "typescript-eslint": "^8.67.0",
     "vite": "^7.2.4",
-    "vite-plugin-dts": "^4.5.4"
+    "vite-plugin-dts": "^4.5.4",
+    "zod": "^3.25.76"
   }
 }

package/skills/arc-diagrams/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: arc-diagrams
+description: Create architecture diagrams using Arc's JSON format. Use when asked to "create an architecture diagram", "draw a system diagram", "visualize the architecture", or "make a diagram of".
+---
+
+# Arc Diagrams
+
+Arc is a visual diagram editor for creating architecture diagrams. This skill enables you to generate Arc-compatible diagram configs that can be rendered in React applications.
+
+## When to Use
+
+Activate this skill when the user asks to:
+- "Create an architecture diagram"
+- "Draw a system diagram"
+- "Visualize the architecture"
+- "Make a diagram showing..."
+- "Design a flow diagram"
+
+## Diagram Format
+
+Arc diagrams are JSON objects with this structure:
+
+```typescript
+interface ArcDiagramData {
+  layout: { width: number; height: number }
+  nodes: Record<string, NodePosition>
+  nodeData: Record<string, NodeData>
+  connectors: Connector[]
+  connectorStyles: Record<string, ConnectorStyle>
+}
+```
+
+## Creating a Diagram
+
+### 1. Define Layout
+
+Set canvas dimensions (default 1600x900 for editor, smaller for exports):
+
+```json
+"layout": { "width": 860, "height": 400 }
+```
+
+### 2. Position Nodes
+
+Each node needs an `x`, `y` position and `size`:
+
+```json
+"nodes": {
+  "frontend": { "x": 50,  "y": 100, "size": "l" },
+  "api":      { "x": 300, "y": 100, "size": "m" },
+  "database": { "x": 550, "y": 100, "size": "m" }
+}
+```
+
+**Size options** (canonical — use these):
+| Size | Key | Dimensions (px) |
+|------|-----|-----------------|
+| Extra Small | `xs` | 80 × 36 |
+| Small | `s` | 110 × 48 |
+| Medium | `m` | 160 × 75 |
+| Large | `l` | 220 × 90 |
+
+Source: `src/utils/constants.ts` → `NODE_SIZES`. Do **not** use `large`/`normal`/`small`.
+
+### 3. Define Node Data
+
+Each node needs an icon, name, and color:
+
+```json
+"nodeData": {
+  "frontend": {
+    "icon": "Monitor",
+    "name": "Frontend",
+    "subtitle": "React",
+    "description": "User interface",
+    "color": "violet"
+  },
+  "api": {
+    "icon": "Server",
+    "name": "API",
+    "subtitle": "Node.js",
+    "description": "REST endpoints",
+    "color": "emerald"
+  },
+  "database": {
+    "icon": "Database",
+    "name": "PostgreSQL",
+    "subtitle": "Storage",
+    "description": "Persistent data",
+    "color": "blue"
+  }
+}
+```
+
+**Available icons (from Lucide):**
+- **Devices:** Monitor, Server, Smartphone, Watch, Cloud, Cpu, Database, HardDrive
+- **Network:** Wifi, Globe
+- **Users:** User, Users
+- **Security:** Lock, Key, Shield
+- **Media:** Mic, Camera, Speaker, Headphones
+- **Code:** Code, Terminal, FileCode, Folder
+- **Data:** Zap, Activity, BarChart, PieChart
+- **Flow:** ArrowRight, ArrowDown, RefreshCw, Repeat
+- **Structure:** Box, Package, Layers, Grid
+- **UI:** Settings, Bell, Mail, MessageSquare, Search, Filter
+- **Actions:** Download, Upload, Play, Pause, Square, Circle
+
+**Available colors:**
+`violet` | `emerald` | `blue` | `amber` | `sky` | `zinc` | `rose` | `orange`
+
+### 4. Connect Nodes
+
+Define connections between nodes:
+
+```json
+"connectors": [
+  {
+    "from": "frontend",
+    "to": "api",
+    "fromAnchor": "right",
+    "toAnchor": "left",
+    "style": "http"
+  },
+  {
+    "from": "api",
+    "to": "database",
+    "fromAnchor": "right",
+    "toAnchor": "left",
+    "style": "sql"
+  }
+]
+```
+
+**Anchor positions:**
+`top` | `bottom` | `left` | `right` | `bottomLeft` | `bottomRight` | `topLeft` | `topRight`
+
+**Optional:** Add `"curve": "natural"` or `"curve": "step"` for curved connectors.
+
+### 5. Style Connectors
+
+Define appearance for each connector style:
+
+```json
+"connectorStyles": {
+  "http": { "color": "amber", "strokeWidth": 2, "label": "HTTP" },
+  "sql": { "color": "blue", "strokeWidth": 2, "label": "SQL" },
+  "async": { "color": "zinc", "strokeWidth": 1.5, "dashed": true }
+}
+```
+
+## Complete Example
+
+Here's a full diagram for a typical web application:
+
+```json
+{
+  "layout": { "width": 700, "height": 300 },
+  "nodes": {
+    "client":   { "x": 50,  "y": 100, "size": "l" },
+    "api":      { "x": 300, "y": 100, "size": "m" },
+    "cache":    { "x": 300, "y": 220, "size": "s" },
+    "database": { "x": 520, "y": 100, "size": "m" }
+  },
+  "nodeData": {
+    "client":   { "icon": "Monitor",  "name": "Client",   "subtitle": "React",    "color": "violet" },
+    "api":      { "icon": "Server",   "name": "API",      "subtitle": "Express",  "color": "emerald" },
+    "cache":    { "icon": "Zap",      "name": "Cache",    "subtitle": "Redis",    "color": "amber" },
+    "database": { "icon": "Database", "name": "Database", "subtitle": "Postgres", "color": "blue" }
+  },
+  "connectors": [
+    { "from": "client", "to": "api",      "fromAnchor": "right",  "toAnchor": "left", "style": "http" },
+    { "from": "api",    "to": "database", "fromAnchor": "right",  "toAnchor": "left", "style": "sql" },
+    { "from": "api",    "to": "cache",    "fromAnchor": "bottom", "toAnchor": "top",  "style": "cache" }
+  ],
+  "connectorStyles": {
+    "http":  { "color": "amber",   "strokeWidth": 2, "label": "HTTP" },
+    "sql":   { "color": "blue",    "strokeWidth": 2, "label": "SQL" },
+    "cache": { "color": "emerald", "strokeWidth": 2, "label": "cache" }
+  }
+}
+```
+
+## Layout Tips
+
+1. **Prefer auto-layout** — use `autoLayout()` from `@arach/arc` when you don't need pixel-perfect placement
+2. **Grid alignment:** Position nodes on a ~50px grid for clean manual layouts
+3. **Spacing:** Leave ~150–200px between connected nodes horizontally
+4. **Flow direction:** Left-to-right or top-to-bottom for data flow
+5. **Grouping:** Use `groups` + `layoutHints` for framed sections (see `docs/group-layout.md`)
+6. **Large nodes:** Use `l` size for primary/entry-point components
+7. **Connectors:** Match connector colors to the source or destination node
+
+## Validation
+
+Before handing off JSON, ensure every `nodes` key has a matching `nodeData` entry.
+In the repo, `validateDiagramShape()` in `src/utils/diagramValidation.ts` returns a
+human-readable error or `null`.
+
+## Output
+
+When generating a diagram, output:
+1. The complete JSON config
+2. Brief explanation of the architecture shown
+3. Suggest the user save it as a `.arc.json` file or paste into the Arc editor
+
+## TypeScript Export
+
+For React projects, diagrams can be exported as TypeScript:
+
+```typescript
+import type { ArcDiagramData } from '@arach/arc'
+
+const diagram: ArcDiagramData = {
+  // ... config here
+}
+
+export default diagram
+```

package/src/types/diagram.ts

@@ -0,0 +1,197 @@
+// Arc Diagram Types
+// Shared format for Arc editor and consumers (Talkie docs, etc.)
+
+import type { NodeShape } from '../utils/nodeShape'
+
+export type { NodeShape }
+
+export type NodeSize = 'xs' | 's' | 'm' | 'l'
+
+export type AnchorPosition =
+  | 'left' | 'right' | 'top' | 'bottom'
+  | 'bottomLeft' | 'bottomRight' | 'topLeft' | 'topRight'
+
+export type DiagramColor =
+  | 'violet' | 'emerald' | 'blue' | 'amber'
+  | 'sky' | 'zinc' | 'rose' | 'orange'
+
+export interface NodePosition {
+  x: number
+  y: number
+  size: NodeSize
+}
+
+export interface NodeData {
+  icon: string
+  name: string
+  subtitle?: string
+  description?: string
+  color: DiagramColor
+  /** Per-node silhouette. Omit to follow the theme's own node shape. */
+  shape?: NodeShape
+}
+
+export interface Connector {
+  from: string
+  to: string
+  fromAnchor: AnchorPosition
+  toAnchor: AnchorPosition
+  style: string
+  curve?: 'natural' | 'step'
+}
+
+export interface ConnectorStyle {
+  color: DiagramColor
+  strokeWidth: number
+  label?: string
+  dashed?: boolean
+}
+
+export interface DiagramLayout {
+  width: number
+  height: number
+}
+
+export interface GridConfig {
+  enabled: boolean
+  size: number
+  color: string
+  opacity: number
+  type: 'dots' | 'lines'
+}
+
+export interface GroupShape {
+  id: string
+  x: number
+  y: number
+  width: number
+  height: number
+  type: 'rect' | 'circle'
+  color: DiagramColor
+  label?: string
+  dashed?: boolean
+}
+
+export interface FocusConnectorRef {
+  from: string
+  to: string
+}
+
+export interface FocusStep {
+  icon: string
+  label: string
+}
+
+/** A declarative highlight story activated by hovering or selecting a node. */
+export interface FocusTarget {
+  /** `append` includes direct neighbors; `replace` uses only the explicit story. */
+  mode?: 'append' | 'replace'
+  nodes?: string[]
+  connectors?: FocusConnectorRef[]
+  caption?: string
+  steps?: FocusStep[]
+}
+
+export type LayoutAlignment = 'start' | 'center' | 'end'
+export type GroupLayoutDirection = 'horizontal' | 'vertical'
+
+/** Optional placement hints used by autoLayout when nodes belong to groups. */
+export interface NodeLayoutHint {
+  /** ID of the group frame that owns this node. */
+  group?: string
+  /** Explicit layer within the group. Connected nodes are layered automatically otherwise. */
+  layer?: number
+  /** Stable ordering within a layer. Lower values render first. */
+  order?: number
+}
+
+/** Layout policy for the nodes inside one group frame. */
+export interface GroupLayoutHint {
+  /** `horizontal` lays layers left-to-right; `vertical` lays them top-to-bottom. */
+  direction?: GroupLayoutDirection
+  padding?: number
+  layerGap?: number
+  itemGap?: number
+  align?: LayoutAlignment
+  justify?: LayoutAlignment | 'space-between'
+}
+
+export interface LayoutHints {
+  nodes?: Record<string, NodeLayoutHint>
+  groups?: Record<string, GroupLayoutHint>
+}
+
+export interface DiagramImage {
+  id: string
+  src: string
+  name: string
+  x: number
+  y: number
+  width: number
+  height: number
+  opacity: number
+}
+
+export interface ExportZone {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+// Full diagram format (internal Arc state)
+export interface ArcDiagram {
+  layout: DiagramLayout
+  grid: GridConfig
+  layoutHints?: LayoutHints
+  nodes: Record<string, NodePosition>
+  nodeData: Record<string, NodeData>
+  connectors: Connector[]
+  connectorStyles: Record<string, ConnectorStyle>
+  groups?: GroupShape[]
+  focusTargets?: Record<string, FocusTarget>
+  images?: DiagramImage[]
+  exportZone?: ExportZone | null
+}
+
+// Clean export format (for consumers)
+export interface ArcDiagramData {
+  id?: string
+  layout: DiagramLayout
+  layoutHints?: LayoutHints
+  nodes: Record<string, NodePosition>
+  nodeData: Record<string, NodeData>
+  connectors: Connector[]
+  connectorStyles: Record<string, ConnectorStyle>
+  focusTargets?: Record<string, FocusTarget>
+  groups?: GroupShape[]
+}
+
+// Convert full diagram to clean export format
+export function toExportFormat(diagram: ArcDiagram): ArcDiagramData {
+  return {
+    layout: diagram.layout,
+    layoutHints: diagram.layoutHints,
+    nodes: diagram.nodes,
+    nodeData: diagram.nodeData,
+    connectors: diagram.connectors,
+    connectorStyles: diagram.connectorStyles,
+    focusTargets: diagram.focusTargets,
+    groups: diagram.groups,
+  }
+}
+
+// Generate TypeScript source file content
+export function toTypeScriptSource(diagram: ArcDiagram, name: string = 'diagram'): string {
+  const data = toExportFormat(diagram)
+  const json = JSON.stringify(data, null, 2)
+    .replace(/"([^"]+)":/g, '$1:') // Remove quotes from keys
+    .replace(/"/g, "'") // Use single quotes
+
+  return `import type { ArcDiagramData } from '@arach/arc'
+
+const ${name}: ArcDiagramData = ${json}
+
+export default ${name}
+`
+}

package/lib/commands_hudsonkit_false-tNYQZ4nZ.js

@@ -1,5 +0,0 @@
-const o = {};
-throw new Error('Could not resolve "@codemirror/commands" imported by "hudsonkit".');
-export {
-  o as default
-};

package/lib/highlight_hudsonkit_false-CGjCyNxW.js

@@ -1,5 +0,0 @@
-const o = {};
-throw new Error('Could not resolve "@lezer/highlight" imported by "hudsonkit".');
-export {
-  o as default
-};

package/lib/lang-css_hudsonkit_false-oeV3Hq1J.js

@@ -1,5 +0,0 @@
-const o = {};
-throw new Error('Could not resolve "@codemirror/lang-css" imported by "hudsonkit".');
-export {
-  o as default
-};