ArcSmith 🛠️📖

ArcSmith is a lightweight, local-first, node-based branching narrative editor designed for game writers, narrative designers, and AI agents. It provides a visual canvas to script complex branching dialogues, logical conditions, variable mutations, and scene transitions, with built-in asset previews for concept art and audio.

Equipped with an embedded Rust-based background REST API, ArcSmith bridges the gap between human designers and AI generators—enabling external scripts or LLMs (Large Language Models) to query, write, and automate the story graph in real-time.

---

✨ Key Features

• Fluid Visual Canvas: Create and connect Dialogue, Monologue, Hub, Condition, Variable Set, and Jump nodes with high-contrast layouts.
• Local Asset Library: Bind concept art, character portraits, and audio files directly to conversation blocks for immersive storytelling.
• Dynamic AI Orchestration API: An integrated local HTTP server (port 14230) exposes the editor state, enabling real-time bidirectional syncing with AI agents.
• State-of-the-Art State Management: Powered by Zustand local store architecture with full Undo/Redo tracking for all canvas manipulations (including those triggered via API).
• Responsive Layout: Curated dark theme, optimized hitboxes for connection handles, fluid grid navigation, and comprehensive keyboard support.
• MDN-Style Documentation Portal: Complete API reference detailing schemas, cascade rules, and action payloads with a built-in LLM integration skill.

---

🏗️ Architecture

ArcSmith is built using a modern, fast, and secure desktop architecture:

• Desktop Shell (Backend): Tauri v2 (Rust) manages window frames, file system access, and spawns the background multi-threaded TCP server on port 14230.
• Canvas Frontend: React 19 + TypeScript + Vite.
• Graph Renderer: @xyflow/react (React Flow) for low-latency node canvas scaling and connection handling.
• State Store: Zustand with custom undo/redo history middleware.
• Styling: Tailwind CSS + Vanilla CSS variables.

---

🚀 Getting Started

Prerequisites

To run and build ArcSmith locally, you will need:

• Node.js (v18 or higher)
• Rust toolchain (latest stable cargo and rustc)

Install Dependencies

npm install

Launch Development Server

Run the Vite development server in the Tauri desktop environment:

npm run tauri dev

This compiles the Rust backend, launches the local API server, and boots the desktop app frame.

Web Build Preview

To build and preview the client bundle:

npm run build

---

🔌 API Reference & AI Integration

ArcSmith launches a loopback HTTP server at http://127.0.0.1:14230 on startup.

CORS Policy

Methods	Access-Control-Allow-Origin	Notes
GET, OPTIONS	*	Read-only — safe to expose broadly
POST, PATCH, DELETE	null	Blocks cross-origin browser requests; curl/Python/Node.js are unaffected

Startup sync: GET /api/project waits up to 2 seconds for the editor to push its initial state, so agents polling immediately on launch always get the real project, never {}.

Core Endpoints

Endpoint	Method	Description
/health	GET	Health check {"status":"ok","version":"1.0.2"}
/api/schema	GET	Machine-readable endpoint listing
/api/project	GET	Fetch the complete project state
/api/project	POST	Replace the entire project state
/api/actions	GET	List valid editor action names
/api/actions	POST	Trigger a UI action (undo, redo, new_project, select_node, set_active_scene)
/api/:resource	GET	List all items (characters, environments, variables, scenes, nodes, connections)
/api/:resource	POST	Create/upsert a resource item (auto-generates id if omitted)
/api/:resource/:id	GET	Fetch a single item by ID
/api/:resource/:id	PATCH	Partial-update an item (shallow-merges fields)
/api/:resource/:id	DELETE	Delete item by ID (full cascade reference cleanup)

HTTP Status Codes

Code	Meaning
200 OK	Success
400 Bad Request	Malformed JSON or bad field values
404 Not Found	Resource or ID not found
405 Method Not Allowed	Includes Allow header
409 Conflict	Attempt to delete the last remaining scene
413 Content Too Large	Body exceeds 20 MB limit
415 Unsupported Media Type	Missing Content-Type: application/json
422 Unprocessable Entity	Valid JSON but missing required node fields (type, sceneId, x, y)
500 Internal Server Error	Internal state error
503 Service Unavailable	Connection limit (32) reached

🤖 LLM Skill (SKILL.md)

A pre-formatted system instruction sheet for AI coding assistants is available directly on the docs site or inside the repository at config/skills/arcsmith-api/SKILL.md. Copy this file into your agent's system prompt or workspace to give it full autonomy to construct narrative graphs for you.

---

📦 Releases & Packaging

To compile and package a production-ready installer (.msi / .exe for Windows, .dmg for macOS, .deb for Linux):

npm run tauri build

The compiled binaries will be outputted under src-tauri/target/release/bundle/.

---

🤝 Contributing

Contributions are welcome! Please check out the issues tab, follow code styling rules, and submit a pull request:

1. Fork the Project.
2. Create your Feature Branch (git checkout -b feature/AmazingFeature).
3. Commit your Changes (git commit -m 'Add some AmazingFeature').
4. Push to the Branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.