From 882668b88c244f87971db50064860a3dfdbdee35 Mon Sep 17 00:00:00 2001 From: lienatanael1-beep Date: Thu, 12 Nov 2026 15:08:24 +0700 Subject: [PATCH 1/2] feat(control): live control port and MCP bridge `anicraft --control ` opens a JSON-lines control port on 127.0.0.1; `anicraft-cli mcp --bridge ` serves the same five MCP tools against the open window. The app runs the CLI's own `mcp::call_tool` (now generic over a `Host`), so live and headless share one dispatcher. A per-run token is written to control.json in the settings folder and removed on exit. Edits wait while the person drags, so undo steps never merge. ADR 0070, docs/control-protocol.md. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 15 + Cargo.lock | 2 + Cargo.toml | 3 + crates/cli/Cargo.toml | 5 +- crates/cli/src/control.rs | 493 +++++++++++++++++++++++++++++ crates/cli/src/control/tests.rs | 253 +++++++++++++++ crates/cli/src/lib.rs | 14 + crates/cli/src/mcp.rs | 82 ++++- docs/adr/0070-live-control-port.md | 99 ++++++ docs/adr/README.md | 1 + docs/control-protocol.md | 103 ++++++ docs/mcp.md | 30 ++ docs/roadmap.md | 2 +- src/app.rs | 10 + src/main.rs | 42 ++- src/panels.rs | 7 + src/platform.rs | 25 ++ src/remote.rs | 143 +++++++++ 18 files changed, 1308 insertions(+), 21 deletions(-) create mode 100644 crates/cli/src/control.rs create mode 100644 crates/cli/src/control/tests.rs create mode 100644 docs/adr/0070-live-control-port.md create mode 100644 docs/control-protocol.md create mode 100644 src/remote.rs diff --git a/CHANGELOG.md b/CHANGELOG.md index b58bef9f..f521c0a7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,21 @@ ## Unreleased +* **Remote control: assistants edit the open window live** (ADR 0070). + * `anicraft --control 9878` opens AniCraft as usual and lets an assistant edit the document you + have open, through a port on this computer only. Its edits appear at once and undo with + Ctrl+Z, like yours; the status bar says "Remote control on (port 9878)" while it is open. Also + `ANICRAFT_CONTROL_PORT`. + * `anicraft-cli mcp --bridge 9878`: the MCP server's five tools, acting on that window. It starts + before AniCraft is open, connects on the first call, says how to start AniCraft when it isn't + running, and reconnects after AniCraft is reopened. + * No setup: each run makes a fresh token and writes it to `control.json` in AniCraft's settings + folder (only you can read it), where the bridge finds it. `ANICRAFT_CONTROL_TOKEN` overrides it. + * While you drag, the assistant's edits wait until you let go, so the two never share an undo step. + * The protocol (`docs/control-protocol.md`): JSON lines on `127.0.0.1`; `hello`, `tools.list`, + `tools.call`; anything that isn't a JSON request (such as a web page's request to localhost) is + refused. + * **The user guide** (ADR 0069, M8). * **Help › User Guide** opens AniCraft's guide in your browser. It comes with the app, so it works offline; the web editor serves it beside the editor. It is also in the command palette. diff --git a/Cargo.lock b/Cargo.lock index c4297341..ed118141 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -219,6 +219,7 @@ name = "anicraft" version = "0.2.1" dependencies = [ "anicraft-audio", + "anicraft-cli", "anicraft-doc", "anicraft-engine", "anicraft-geom", @@ -269,6 +270,7 @@ dependencies = [ "anicraft-geom", "anicraft-guide", "anicraft-render", + "getrandom 0.3.4", "serde_json", ] diff --git a/Cargo.toml b/Cargo.toml index 2c6d31cb..334a68e4 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -112,6 +112,9 @@ sys-locale = "0.3" [target.'cfg(not(target_arch = "wasm32"))'.dependencies] # The user guide, bundled for Help › User Guide (ADR 0069). The web build serves it as pages instead. anicraft-guide.workspace = true +# The live control port and the tools it serves (ADR 0070): the same dispatcher as the +# headless MCP server, so live and headless never drift. +anicraft-cli = { path = "crates/cli" } craft-update = { git = "https://github.com/storytold/craft-libs", rev = "6ac2a6a34ae83fc0f0bfb25a569ba6388b72266a" } eframe = { workspace = true, features = ["links"] } diff --git a/crates/cli/Cargo.toml b/crates/cli/Cargo.toml index 621e7b3f..4d3a2546 100644 --- a/crates/cli/Cargo.toml +++ b/crates/cli/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "anicraft-cli" -description = "AniCraft L4: headless CLI and JSON-lines control channel for agents and pipelines" +description = "AniCraft L4: headless CLI, MCP server and the desktop app's live control channel" version.workspace = true edition.workspace = true license.workspace = true @@ -21,6 +21,9 @@ anicraft-render.workspace = true anicraft-geom.workspace = true anicraft-guide.workspace = true serde_json.workspace = true +# The live control port's per-run token (ADR 0070): the operating system's random numbers. +# MIT OR Apache-2.0, already in the tree. +getrandom = "0.3" [lints] workspace = true diff --git a/crates/cli/src/control.rs b/crates/cli/src/control.rs new file mode 100644 index 00000000..adb1d256 --- /dev/null +++ b/crates/cli/src/control.rs @@ -0,0 +1,493 @@ +//! The live control channel (ADR 0070, `docs/control-protocol.md`): the desktop app's control +//! port, and the client `anicraft-cli mcp --bridge ` uses to reach it. +//! +//! The app listens on `127.0.0.1` only. Each connection carries one JSON object per line each +//! way, answered in order. Every request carries the run's token, which the app writes to +//! `control.json` in the AniCraft settings folder, so a client running as the same user finds it +//! with no setup. The tools are the MCP server's ([`crate::mcp::tools`], [`crate::mcp::call_tool`]), +//! so live and headless never drift. +//! +//! Nothing here touches the window: [`listen`] hands each tool call to whoever drains +//! [`Server::try_recv`] (the app's frame loop), with a channel for the answer. + +use crate::mcp; +use serde_json::{Value, json}; +use std::io::{BufRead, BufReader, Read, Write}; +use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4, TcpListener, TcpStream}; +use std::path::{Path, PathBuf}; +use std::sync::Arc; +use std::sync::atomic::{AtomicUsize, Ordering}; +use std::sync::mpsc::{Receiver, RecvTimeoutError, Sender, channel}; +use std::time::{Duration, Instant}; + +/// The wire protocol's version, reported by `hello`. +pub const PROTOCOL: u32 = 1; +/// The port AniCraft's documentation and shortcuts use (VectorCraft 7979, CadCraft 7980, +/// FilmCraft 9876, EffectCraft 9877). +pub const DEFAULT_PORT: u16 = 9878; +/// Longest request or reply line, in bytes. +pub const MAX_LINE: usize = 4 * 1024 * 1024; +/// Most connections open at once. +pub const MAX_CONNECTIONS: usize = 16; +/// How long a tool call may wait for the app (a frame, or the end of the person's drag). +pub const REQUEST_TIMEOUT: Duration = Duration::from_secs(60); +/// Extra time the connection waits past the deadline: a call that started just before it +/// still gets its real answer. +const GRACE: Duration = Duration::from_secs(10); +/// Overrides the generated token on both sides (CI, power users). +pub const TOKEN_ENV: &str = "ANICRAFT_CONTROL_TOKEN"; +/// The port when `--control` isn't given. +pub const PORT_ENV: &str = "ANICRAFT_CONTROL_PORT"; +/// The file the app writes in the settings folder while its control port is open. +pub const CONTROL_FILE: &str = "control.json"; + +/// AniCraft's settings folder: %APPDATA%\AniCraft, ~/Library/Application Support/AniCraft, or +/// $XDG_CONFIG_HOME/anicraft (default ~/.config/anicraft). The shell's `platform::config_dir` +/// owns this rule; a shell test keeps the two the same (this crate can't use the shell). +pub fn settings_dir() -> Option { + let env = |k: &str| std::env::var_os(k).filter(|v| !v.is_empty()).map(PathBuf::from); + if cfg!(windows) { + env("APPDATA").map(|p| p.join("AniCraft")) + } else if cfg!(target_os = "macos") { + env("HOME").map(|p| p.join("Library").join("Application Support").join("AniCraft")) + } else { + env("XDG_CONFIG_HOME").or_else(|| env("HOME").map(|h| h.join(".config"))).map(|p| p.join("anicraft")) + } +} + +/// Where `control.json` lives. +pub fn control_file() -> Option { + settings_dir().map(|d| d.join(CONTROL_FILE)) +} + +/// `ANICRAFT_CONTROL_TOKEN`, when set and not blank. +pub fn token_from_env() -> Option { + std::env::var(TOKEN_ENV).ok().map(|t| t.trim().to_string()).filter(|t| !t.is_empty()) +} + +/// A fresh token: 32 random bytes from the operating system, as 64 hex digits. +pub fn new_token() -> Result { + let mut bytes = [0u8; 32]; + getrandom::fill(&mut bytes).map_err(|e| format!("no random numbers from the system: {e}"))?; + Ok(bytes.iter().map(|b| format!("{b:02x}")).collect()) +} + +/// Reads a port: a number from 1 to 65535. +pub fn parse_port(s: &str) -> Result { + match s.trim().parse::() { + Ok(p) if p > 0 => Ok(p), + _ => Err(format!("'{s}' is not a port: use a number from 1 to 65535, such as {DEFAULT_PORT}")), + } +} + +/// What `control.json` holds. +#[derive(Clone, Debug, PartialEq)] +pub struct ControlFile { + pub port: u16, + pub token: String, + pub pid: u32, + pub version: String, +} + +impl ControlFile { + pub fn to_json(&self) -> Value { + json!({"port": self.port, "token": self.token, "pid": self.pid, "version": self.version}) + } + pub fn parse(text: &str) -> Result { + let v: Value = serde_json::from_str(text.trim_start_matches('\u{feff}')).map_err(|e| format!("{CONTROL_FILE} is not JSON: {e}"))?; + let token = v.get("token").and_then(Value::as_str).filter(|t| !t.is_empty()).ok_or_else(|| format!("{CONTROL_FILE} has no token"))?; + let port = v.get("port").and_then(Value::as_u64).and_then(|p| u16::try_from(p).ok()).ok_or_else(|| format!("{CONTROL_FILE} has no port"))?; + let pid = v.get("pid").and_then(Value::as_u64).and_then(|p| u32::try_from(p).ok()).unwrap_or(0); + let version = v.get("version").and_then(Value::as_str).unwrap_or("").to_string(); + Ok(ControlFile { port, token: token.to_string(), pid, version }) + } +} + +/// Why a line could not be read. +#[derive(Debug)] +pub enum LineError { + TooLong, + NotText, + Io(std::io::Error), +} + +/// Reads one line (without its line break), at most `limit` bytes; `Ok(None)` at the end. +pub fn read_line(r: &mut R, limit: usize) -> Result, LineError> { + let mut buf = Vec::new(); + let cap = u64::try_from(limit).unwrap_or(u64::MAX).saturating_add(1); + let n = r.by_ref().take(cap).read_until(b'\n', &mut buf).map_err(LineError::Io)?; + if n == 0 { + return Ok(None); + } + if buf.last() == Some(&b'\n') { + buf.pop(); + } else if buf.len() > limit { + return Err(LineError::TooLong); + } + if buf.len() > limit { + return Err(LineError::TooLong); + } + if buf.last() == Some(&b'\r') { + buf.pop(); + } + String::from_utf8(buf).map(Some).map_err(|_| LineError::NotText) +} + +/// One request off the wire. +#[derive(Debug, PartialEq)] +pub struct Incoming { + pub id: Value, + pub token: Option, + pub method: String, + pub params: Value, +} + +/// Reads a request line: a JSON object with a string `method`. Anything else (an HTTP request +/// line, which is how a web page's `fetch` to localhost begins, included) is refused. +pub fn parse_request(line: &str) -> Result { + let v: Value = serde_json::from_str(line.trim_start_matches('\u{feff}')).map_err(|_| "expected one JSON object per line, such as {\"id\":1,\"token\":\"…\",\"method\":\"hello\"}".to_string())?; + let Value::Object(mut o) = v else { return Err("expected a JSON object".into()) }; + let method = match o.remove("method") { + Some(Value::String(m)) => m, + _ => return Err("the request needs a string \"method\"".into()), + }; + let token = match o.remove("token") { + Some(Value::String(t)) => Some(t), + _ => None, + }; + Ok(Incoming { id: o.remove("id").unwrap_or(Value::Null), token, method, params: o.remove("params").unwrap_or_else(|| json!({})) }) +} + +/// Compares tokens in time that doesn't depend on where they differ. +pub fn token_matches(given: Option<&str>, expected: &str) -> bool { + let Some(given) = given else { return false }; + let (a, b) = (given.as_bytes(), expected.as_bytes()); + a.len() == b.len() && !b.is_empty() && a.iter().zip(b).fold(0u8, |acc, (x, y)| acc | (x ^ y)) == 0 +} + +fn ok(id: &Value, result: Value) -> Value { + json!({"id": id, "ok": true, "result": result}) +} + +fn fail(id: &Value, error: impl Into) -> Value { + json!({"id": id, "ok": false, "error": error.into()}) +} + +/// The message when a tool call never got its turn. +pub const BUSY: &str = "AniCraft was busy for 60 s (an edit in progress in the window, such as a drag, typing or a plug-in dialog), so this call was not run. Try again."; + +/// A tool call waiting for the app's frame loop. +pub struct Request { + pub name: String, + pub arguments: Value, + deadline: Instant, + reply: Sender>, +} + +impl Request { + /// Whether it can change the document (and so waits for the person's own gesture to end). + pub fn changes_document(&self) -> bool { + mcp::tool_changes_document(&self.name) + } + /// Past its deadline: it must not run any more (the client was told it didn't). + pub fn expired(&self) -> bool { + Instant::now() >= self.deadline + } + /// Runs it on `host` and sends the answer; an expired request is refused instead. + pub fn run(self, host: &mut H) { + let result = if self.expired() { Err(BUSY.to_string()) } else { mcp::call_tool(host, &self.name, &self.arguments) }; + let _ = self.reply.send(result); + } + /// Answers without running (the app is closing). + pub fn refuse(self, why: &str) { + let _ = self.reply.send(Err(why.to_string())); + } +} + +/// Wakes the app's frame loop (`egui::Context::request_repaint`), from any thread. +pub type Wake = Arc; + +/// An open control port. +pub struct Server { + pub port: u16, + rx: Receiver, +} + +impl Server { + /// The next waiting tool call, if any. + pub fn try_recv(&self) -> Option { + self.rx.try_recv().ok() + } +} + +/// Opens the control port on `127.0.0.1:port`. Tool calls arrive through [`Server::try_recv`]; +/// `wake` is called whenever one is waiting. +pub fn listen(port: u16, token: String, wake: Wake) -> std::io::Result { + let listener = TcpListener::bind(SocketAddrV4::new(Ipv4Addr::LOCALHOST, port))?; + let port = listener.local_addr()?.port(); + let (tx, rx) = channel(); + let token: Arc = token.into(); + std::thread::Builder::new().name("anicraft-control".into()).spawn(move || accept_loop(&listener, &token, &tx, &wake))?; + Ok(Server { port, rx }) +} + +fn accept_loop(listener: &TcpListener, token: &Arc, tx: &Sender, wake: &Wake) { + let active = Arc::new(AtomicUsize::new(0)); + for stream in listener.incoming() { + let Ok(mut stream) = stream else { continue }; + let _ = stream.set_write_timeout(Some(Duration::from_secs(10))); + if active.fetch_add(1, Ordering::SeqCst) >= MAX_CONNECTIONS { + active.fetch_sub(1, Ordering::SeqCst); + let _ = writeln!(stream, "{}", fail(&Value::Null, format!("too many connections (at most {MAX_CONNECTIONS})"))); + continue; + } + let (token, tx, wake, active2) = (token.clone(), tx.clone(), wake.clone(), active.clone()); + let spawned = std::thread::Builder::new().name("anicraft-control-conn".into()).spawn(move || { + serve_connection(stream, &token, &tx, &wake); + active2.fetch_sub(1, Ordering::SeqCst); + }); + if spawned.is_err() { + active.fetch_sub(1, Ordering::SeqCst); + } + } +} + +/// One connection: requests in order, until the client leaves or sends something it shouldn't. +fn serve_connection(stream: TcpStream, token: &str, tx: &Sender, wake: &Wake) { + let Ok(read_half) = stream.try_clone() else { return }; + let mut reader = BufReader::new(read_half); + let mut out = stream; + loop { + let line = match read_line(&mut reader, MAX_LINE) { + Ok(Some(l)) => l, + Ok(None) | Err(LineError::Io(_)) => return, + Err(LineError::TooLong) => { + let _ = writeln!(out, "{}", fail(&Value::Null, format!("request longer than {} MiB", MAX_LINE / (1024 * 1024)))); + return; + } + Err(LineError::NotText) => { + let _ = writeln!(out, "{}", fail(&Value::Null, "the request is not UTF-8 text")); + return; + } + }; + if line.trim().is_empty() { + continue; + } + let (reply, keep_open) = answer(&line, token, tx, wake); + if writeln!(out, "{reply}").and_then(|()| out.flush()).is_err() || !keep_open { + return; + } + } +} + +/// The reply to one request line, and whether the connection stays open. +fn answer(line: &str, token: &str, tx: &Sender, wake: &Wake) -> (Value, bool) { + let req = match parse_request(line) { + Ok(r) => r, + Err(e) => return (fail(&Value::Null, e), false), + }; + if !token_matches(req.token.as_deref(), token) { + let why = if req.token.is_none() { "missing token" } else { "wrong token" }; + return (fail(&req.id, format!("{why}: send the \"token\" from {CONTROL_FILE} in AniCraft's settings folder (or {TOKEN_ENV})")), false); + } + let id = &req.id; + match req.method.as_str() { + "hello" => (ok(id, json!({"app": "AniCraft", "version": env!("CARGO_PKG_VERSION"), "protocol": PROTOCOL})), true), + "tools.list" => (ok(id, mcp::tools()), true), + "tools.call" => { + let Some(name) = req.params.get("name").and_then(Value::as_str) else { return (fail(id, "tools.call needs a tool \"name\" in params"), true) }; + let arguments = req.params.get("arguments").cloned().unwrap_or_else(|| json!({})); + let (reply, rx) = channel(); + let request = Request { name: name.to_string(), arguments, deadline: Instant::now() + REQUEST_TIMEOUT, reply }; + if tx.send(request).is_err() { + return (fail(id, "AniCraft is closing"), false); + } + wake(); + match rx.recv_timeout(REQUEST_TIMEOUT + GRACE) { + Ok(Ok(result)) => (ok(id, result), true), + Ok(Err(e)) => (fail(id, e), true), + Err(RecvTimeoutError::Timeout) => (fail(id, "AniCraft didn't answer in time; the call may still have run. Check with anicraft_document before trying again."), true), + Err(RecvTimeoutError::Disconnected) => (fail(id, "AniCraft closed before answering"), false), + } + } + other => (fail(id, format!("unknown method '{other}' (hello, tools.list, tools.call)")), true), + } +} + +// ----- the client: `anicraft-cli mcp --bridge` ------------------------------------------------- + +/// Reads `--bridge`'s value: a port, or `127.0.0.1:port` / `localhost:port`. Other hosts are +/// refused: the control port is for this computer only. +pub fn parse_bridge_target(s: &str) -> Result { + let s = s.trim(); + let (host, port) = match s.rsplit_once(':') { + Some((h, p)) => (h, p), + None => ("127.0.0.1", s), + }; + if !matches!(host, "127.0.0.1" | "localhost") { + return Err(format!("--bridge connects to this computer only: give a port, or 127.0.0.1: (not {host})")); + } + Ok(SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::LOCALHOST, parse_port(port)?))) +} + +/// The token to send: `ANICRAFT_CONTROL_TOKEN` when set, else the one in `control.json`. +pub fn find_token(env: Option, file: Option<&Path>) -> Result { + if let Some(t) = env { + return Ok(t); + } + let Some(file) = file else { return Err(not_running(None)) }; + match std::fs::read_to_string(file) { + Ok(text) => ControlFile::parse(&text).map(|c| c.token), + Err(_) => Err(not_running(None)), + } +} + +/// What to tell the person when the app isn't there. +fn not_running(port: Option) -> String { + let port = port.unwrap_or(DEFAULT_PORT); + format!( + "AniCraft isn't open with remote control on. Start it with `anicraft --control {port}` (the \"AniCraft (Claude)\" shortcut), then try again; there is no need to restart the assistant." + ) +} + +/// Why a bridged call failed. +#[derive(Debug, PartialEq)] +pub enum BridgeError { + /// Couldn't reach the app (not running, no token): nothing ran. + NotRunning(String), + /// The connection broke after the request went out: it may have run. + Lost(String), + /// The app refused the call (the headless server's protocol error). + Refused(String), +} + +struct Conn { + reader: BufReader, + writer: TcpStream, +} + +impl Conn { + /// Whether the app is still at the other end (an app that quit leaves the socket closed). + fn alive(&self) -> bool { + if self.writer.set_nonblocking(true).is_err() { + return false; + } + let r = self.writer.peek(&mut [0u8; 1]); + let back = self.writer.set_nonblocking(false).is_ok(); + back && matches!(r, Err(ref e) if e.kind() == std::io::ErrorKind::WouldBlock) + } +} + +/// The bridge's link to the app: connected on the first call, again after a break. +pub struct Bridge { + addr: SocketAddr, + conn: Option, + next_id: u64, + /// Where the token comes from (tests point it elsewhere). + token_file: Option, +} + +impl Bridge { + /// Doesn't connect: the assistant starts its servers when it starts, often before AniCraft. + pub fn new(addr: SocketAddr) -> Bridge { + Bridge { addr, conn: None, next_id: 1, token_file: control_file() } + } + + pub fn with_token_file(addr: SocketAddr, file: Option) -> Bridge { + Bridge { addr, conn: None, next_id: 1, token_file: file } + } + + fn connect(&mut self) -> Result { + let token = find_token(token_from_env(), self.token_file.as_deref()).map_err(BridgeError::NotRunning)?; + if self.conn.as_ref().is_some_and(Conn::alive) { + return Ok(token); + } + self.conn = None; + let stream = TcpStream::connect_timeout(&self.addr, Duration::from_secs(3)).map_err(|_| BridgeError::NotRunning(not_running(Some(self.addr.port()))))?; + let _ = stream.set_nodelay(true); + let _ = stream.set_read_timeout(Some(REQUEST_TIMEOUT + GRACE + Duration::from_secs(5))); + let reader = BufReader::new(stream.try_clone().map_err(|e| BridgeError::NotRunning(e.to_string()))?); + self.conn = Some(Conn { reader, writer: stream }); + Ok(token) + } + + /// One round trip; any transport failure drops the connection. + fn round_trip(&mut self, token: &str, method: &str, params: Value) -> Result { + let id = self.next_id; + self.next_id += 1; + let line = json!({"id": id, "token": token, "method": method, "params": params}).to_string(); + let Some(conn) = self.conn.as_mut() else { return Err(BridgeError::NotRunning(not_running(Some(self.addr.port())))) }; + let sent = writeln!(conn.writer, "{line}").and_then(|()| conn.writer.flush()); + let reply = sent.map_err(|e| e.to_string()).and_then(|()| match read_line(&mut conn.reader, MAX_LINE) { + Ok(Some(l)) => Ok(l), + Ok(None) => Err("AniCraft closed the connection".to_string()), + Err(LineError::Io(e)) => Err(e.to_string()), + Err(_) => Err("unreadable reply".to_string()), + }); + let reply = match reply { + Ok(l) => l, + Err(e) => { + self.conn = None; + return Err(BridgeError::Lost(e)); + } + }; + let v: Value = serde_json::from_str(&reply).map_err(|e| { + self.conn = None; + BridgeError::Lost(format!("unreadable reply: {e}")) + })?; + if v.get("ok").and_then(Value::as_bool) == Some(true) { + return Ok(v.get("result").cloned().unwrap_or(Value::Null)); + } + let error = v.get("error").and_then(Value::as_str).unwrap_or("AniCraft refused the request").to_string(); + if v.get("id").is_some_and(Value::is_null) || error.starts_with("missing token") || error.starts_with("wrong token") { + // The app closes the connection after these (an old token: AniCraft was restarted + // and control.json has the new one by the next call). + self.conn = None; + } + Err(BridgeError::Refused(error)) + } + + /// Runs a tool in the app. An edit whose answer was lost is never sent again (the app may + /// have made it); a call that only reads is tried once more on a new connection. + pub fn call_tool(&mut self, name: &str, args: &Value) -> Result { + let retries = if mcp::tool_changes_document(name) { 0 } else { 1 }; + let mut attempt = 0; + loop { + let token = self.connect()?; + match self.round_trip(&token, "tools.call", json!({"name": name, "arguments": args})) { + Err(BridgeError::Lost(_)) if attempt < retries => attempt += 1, + Err(BridgeError::Refused(e)) if e.starts_with("wrong token") && attempt < 1 => attempt += 1, + other => return other, + } + } + } +} + +/// The bridge's instructions: the same tools, acting on the person's open window. +pub const BRIDGE_INSTRUCTIONS: &str = "AniCraft is a 2D animation studio, and these tools act on the AniCraft window the person \ +has open: every edit appears there immediately and can be undone with Ctrl+Z (or edit.undo). Every edit is a command: call \ +anicraft_commands to find one (filter by words such as 'tween' or 'export'), then anicraft_run with its id and params, or \ +anicraft_run_script for several in order. Frames in params are 0-based. Commands act on the current scene, layer, frame and \ +selection, which anicraft_document reports (the person may change them between your calls). Use anicraft_render to see a \ +frame. Commands that would lose work or replace a file refuse until params include \"confirm\": true; ask the person before \ +confirming. If AniCraft isn't open with remote control on, the tools say how to start it."; + +impl mcp::Backend for Bridge { + fn instructions(&self) -> &'static str { + BRIDGE_INSTRUCTIONS + } + fn call(&mut self, name: &str, args: &Value) -> Result { + match self.call_tool(name, args) { + Ok(v) => Ok(v), + Err(BridgeError::Refused(e)) => Err(e), + Err(BridgeError::NotRunning(e)) => Ok(mcp::text_result(&Value::String(e), true)), + Err(BridgeError::Lost(e)) => { + let what = if mcp::tool_changes_document(name) { " It may have been made: check with anicraft_document before trying again." } else { "" }; + Ok(mcp::text_result(&Value::String(format!("The connection to AniCraft broke ({e}).{what}")), true)) + } + } + } +} + +#[cfg(test)] +mod tests; diff --git a/crates/cli/src/control/tests.rs b/crates/cli/src/control/tests.rs new file mode 100644 index 00000000..1c136fc6 --- /dev/null +++ b/crates/cli/src/control/tests.rs @@ -0,0 +1,253 @@ +use super::*; +use crate::mcp::Backend; +use anicraft_engine::Session; +use std::sync::atomic::AtomicBool; + +const TOKEN: &str = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"; + +/// A control port on a free port, with a stand-in for the app's frame loop running each call on +/// its own session (as `App::poll_remote` does). Stops when dropped. +struct App { + port: u16, + stop: Arc, + loop_thread: Option>, +} + +impl App { + fn start(session: Session) -> App { + let server = listen(0, TOKEN.into(), Arc::new(|| {})).unwrap(); + let port = server.port; + let stop = Arc::new(AtomicBool::new(false)); + let stop2 = stop.clone(); + let loop_thread = std::thread::spawn(move || { + let mut s = session; + while !stop2.load(Ordering::SeqCst) { + while let Some(r) = server.try_recv() { + r.run(&mut s); + } + std::thread::sleep(Duration::from_millis(2)); + } + s + }); + App { port, stop, loop_thread: Some(loop_thread) } + } + + fn session(mut self) -> Session { + self.stop.store(true, Ordering::SeqCst); + self.loop_thread.take().unwrap().join().unwrap() + } + + fn connect(&self) -> (BufReader, TcpStream) { + let s = TcpStream::connect(("127.0.0.1", self.port)).unwrap(); + s.set_read_timeout(Some(Duration::from_secs(20))).unwrap(); + (BufReader::new(s.try_clone().unwrap()), s) + } +} + +impl Drop for App { + fn drop(&mut self) { + self.stop.store(true, Ordering::SeqCst); + } +} + +fn send(conn: &mut (BufReader, TcpStream), line: &str) -> Value { + writeln!(conn.1, "{line}").unwrap(); + serde_json::from_str(&read_line(&mut conn.0, MAX_LINE).unwrap().unwrap()).unwrap() +} + +/// The app closed the connection: nothing more to read. +fn closed(conn: &mut (BufReader, TcpStream)) -> bool { + matches!(read_line(&mut conn.0, MAX_LINE), Ok(None) | Err(LineError::Io(_))) +} + +#[test] +fn requests_are_json_objects_with_a_string_method() { + let r = parse_request(r#"{"id":3,"token":"t","method":"hello"}"#).unwrap(); + assert_eq!((r.id, r.token.as_deref(), r.method.as_str(), r.params), (json!(3), Some("t"), "hello", json!({}))); + // A web page's fetch to localhost starts with an HTTP request line: refused. + assert!(parse_request("GET / HTTP/1.1").is_err()); + assert!(parse_request("POST /tools HTTP/1.1").is_err()); + assert!(parse_request("[1,2]").is_err()); + assert!(parse_request(r#"{"id":1}"#).is_err(), "no method"); + assert!(parse_request(r#"{"id":1,"method":7}"#).is_err(), "method must be a string"); +} + +#[test] +fn tokens_must_match_exactly() { + assert!(token_matches(Some(TOKEN), TOKEN)); + assert!(!token_matches(None, TOKEN)); + assert!(!token_matches(Some(""), ""), "an empty token never opens the port"); + assert!(!token_matches(Some(&TOKEN[..63]), TOKEN)); + assert!(!token_matches(Some(&TOKEN.replace('f', "e")), TOKEN)); + let t = new_token().unwrap(); + assert_eq!(t.len(), 64); + assert!(t.bytes().all(|b| b.is_ascii_hexdigit())); + assert_ne!(t, new_token().unwrap(), "fresh each time"); +} + +#[test] +fn lines_are_capped() { + let mut r = &b"one\r\ntwo\nthree"[..]; + assert_eq!(read_line(&mut r, 10).unwrap().as_deref(), Some("one")); + assert_eq!(read_line(&mut r, 10).unwrap().as_deref(), Some("two")); + assert_eq!(read_line(&mut r, 10).unwrap().as_deref(), Some("three")); + assert!(read_line(&mut r, 10).unwrap().is_none()); + let mut exact = &b"0123456789\n"[..]; + assert_eq!(read_line(&mut exact, 10).unwrap().as_deref(), Some("0123456789")); + let mut long = &b"0123456789A\n"[..]; + assert!(matches!(read_line(&mut long, 10), Err(LineError::TooLong))); +} + +#[test] +fn ports_and_bridge_targets() { + assert_eq!(parse_port("9878"), Ok(9878)); + assert!(parse_port("0").is_err()); + assert!(parse_port("70000").is_err()); + assert!(parse_port("port").is_err()); + let local = SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::LOCALHOST, 9878)); + assert_eq!(parse_bridge_target("9878"), Ok(local)); + assert_eq!(parse_bridge_target("127.0.0.1:9878"), Ok(local)); + assert_eq!(parse_bridge_target("localhost:9878"), Ok(local)); + assert!(parse_bridge_target("192.168.1.5:9878").is_err(), "this computer only"); + assert!(parse_bridge_target("example.com:9878").is_err()); +} + +#[test] +fn the_control_file_round_trips() { + let c = ControlFile { port: 9878, token: TOKEN.into(), pid: 42, version: "0.2.1".into() }; + assert_eq!(ControlFile::parse(&c.to_json().to_string()), Ok(c)); + assert!(ControlFile::parse("{}").is_err()); + assert!(ControlFile::parse("nonsense").is_err()); +} + +#[test] +fn the_token_comes_from_the_environment_then_the_control_file() { + let dir = std::env::temp_dir().join(format!("anicraft-control-token-{}", std::process::id())); + std::fs::create_dir_all(&dir).unwrap(); + let file = dir.join(CONTROL_FILE); + std::fs::write(&file, ControlFile { port: 9878, token: "from-file".into(), pid: 1, version: String::new() }.to_json().to_string()).unwrap(); + assert_eq!(find_token(Some("from-env".into()), Some(&file)), Ok("from-env".into()), "the environment wins"); + assert_eq!(find_token(None, Some(&file)), Ok("from-file".into())); + let missing = find_token(None, Some(&dir.join("gone.json"))).unwrap_err(); + assert!(missing.contains("anicraft --control"), "{missing}"); + assert!(find_token(None, None).is_err()); + let _ = std::fs::remove_dir_all(&dir); +} + +#[test] +fn a_missing_or_wrong_token_is_refused_and_the_connection_closed() { + let app = App::start(Session::default()); + let mut c = app.connect(); + let r = send(&mut c, r#"{"id":1,"method":"tools.call","params":{"name":"anicraft_run","arguments":{"command":"draw.rect","params":{"x":0,"y":0,"w":5,"h":5}}}}"#); + assert_eq!(r["ok"], false); + assert!(r["error"].as_str().unwrap().starts_with("missing token"), "{r}"); + assert!(closed(&mut c)); + let mut c = app.connect(); + let r = send(&mut c, &json!({"id": 2, "token": "nope", "method": "tools.call", "params": {"name": "anicraft_run", "arguments": {"command": "draw.rect", "params": {"x": 0, "y": 0, "w": 5, "h": 5}}}}).to_string()); + assert!(r["error"].as_str().unwrap().starts_with("wrong token"), "{r}"); + assert!(closed(&mut c)); + assert!(app.session().visible_elements().is_empty(), "nothing ran"); +} + +#[test] +fn http_and_oversized_lines_are_refused_and_the_connection_closed() { + let app = App::start(Session::default()); + let mut c = app.connect(); + let r = send(&mut c, "GET / HTTP/1.1\r\nHost: 127.0.0.1\r\n"); + assert_eq!((r["ok"].clone(), r["id"].clone()), (json!(false), Value::Null)); + assert!(closed(&mut c)); + let mut c = app.connect(); + let big = format!(r#"{{"id":1,"token":"{TOKEN}","method":"hello","pad":"{}"}}"#, "x".repeat(MAX_LINE)); + // The app stops reading at the limit and answers; the rest of the write may fail. + let _ = c.1.write_all(big.as_bytes()); + let _ = c.1.write_all(b"\n"); + let reply: Value = serde_json::from_str(&read_line(&mut c.0, MAX_LINE).unwrap().unwrap()).unwrap(); + assert!(reply["error"].as_str().unwrap().contains("longer than 4 MiB"), "{reply}"); + assert!(closed(&mut c)); +} + +#[test] +fn a_call_through_the_port_matches_the_headless_server() { + let app = App::start(Session::default()); + let mut c = app.connect(); + let hello = send(&mut c, &json!({"id": 1, "token": TOKEN, "method": "hello"}).to_string()); + assert_eq!(hello, json!({"id": 1, "ok": true, "result": {"app": "AniCraft", "version": env!("CARGO_PKG_VERSION"), "protocol": PROTOCOL}})); + let list = send(&mut c, &json!({"id": 2, "token": TOKEN, "method": "tools.list"}).to_string()); + assert_eq!(list["result"], mcp::tools()); + let args = json!({"command": "draw.rect", "params": {"x": 10, "y": 10, "w": 50, "h": 40, "fill": "#ff0000"}}); + let live = send(&mut c, &json!({"id": 3, "token": TOKEN, "method": "tools.call", "params": {"name": "anicraft_run", "arguments": args}}).to_string()); + assert_eq!(live["ok"], true, "{live}"); + let mut headless = Session::default(); + assert_eq!(live["result"], mcp::call_tool(&mut headless, "anicraft_run", &args).unwrap(), "the same dispatcher, the same answer"); + // A protocol error in headless mode is an error reply here; the connection stays usable. + let bad = send(&mut c, &json!({"id": 4, "token": TOKEN, "method": "tools.call", "params": {"name": "nope"}}).to_string()); + assert_eq!((bad["ok"].clone(), bad["error"].clone()), (json!(false), json!("unknown tool 'nope'"))); + let unknown = send(&mut c, &json!({"id": 5, "token": TOKEN, "method": "frobnicate"}).to_string()); + assert_eq!(unknown["ok"], false); + let doc = send(&mut c, &json!({"id": 6, "token": TOKEN, "method": "tools.call", "params": {"name": "anicraft_document"}}).to_string()); + // `state` numbers saved states across every session in the process, so it differs. + let described = |r: &Value| { + let mut v: Value = serde_json::from_str(r["content"][0]["text"].as_str().unwrap()).unwrap(); + v.as_object_mut().unwrap().remove("state"); + v + }; + assert_eq!(described(&doc["result"]), described(&mcp::call_tool(&mut headless, "anicraft_document", &json!({})).unwrap())); + let s = app.session(); + assert_eq!(s.visible_elements().len(), 1); + assert!(s.doc == headless.doc); +} + +#[test] +fn a_call_that_waited_past_its_deadline_does_not_run() { + let (reply, answer) = channel(); + let r = Request { name: "anicraft_run".into(), arguments: json!({"command": "draw.rect", "params": {"x": 0, "y": 0, "w": 5, "h": 5}}), deadline: Instant::now(), reply }; + assert!(r.expired() && r.changes_document()); + let mut s = Session::default(); + r.run(&mut s); + assert_eq!(answer.recv().unwrap(), Err(BUSY.to_string())); + assert!(s.visible_elements().is_empty()); +} + +fn free_port() -> u16 { + TcpListener::bind("127.0.0.1:0").unwrap().local_addr().unwrap().port() +} + +#[test] +fn the_bridge_starts_without_the_app_and_says_how_to_start_it() { + let addr = SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::LOCALHOST, free_port())); + let dir = std::env::temp_dir().join(format!("anicraft-bridge-none-{}", std::process::id())); + let mut b = Bridge::with_token_file(addr, Some(dir.join(CONTROL_FILE))); + // The handshake and the tool list need no app. + let init = mcp::handle(&mut b, r#"{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}"#).unwrap(); + assert!(init["result"]["instructions"].as_str().unwrap().contains("open")); + let list = mcp::handle(&mut b, r#"{"jsonrpc":"2.0","id":2,"method":"tools/list"}"#).unwrap(); + assert_eq!(list["result"]["tools"], mcp::tools()); + let r = mcp::handle(&mut b, r#"{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"anicraft_document"}}"#).unwrap(); + assert_eq!(r["result"]["isError"], true); + assert!(r["result"]["content"][0]["text"].as_str().unwrap().contains("anicraft --control"), "{r}"); + // A token file but no app listening: the same advice. + std::fs::create_dir_all(&dir).unwrap(); + std::fs::write(dir.join(CONTROL_FILE), ControlFile { port: addr.port(), token: TOKEN.into(), pid: 1, version: String::new() }.to_json().to_string()).unwrap(); + assert!(matches!(b.call_tool("anicraft_document", &json!({})), Err(BridgeError::NotRunning(_)))); + let _ = std::fs::remove_dir_all(&dir); +} + +#[test] +fn the_bridge_drives_the_app_and_says_when_it_has_gone() { + let dir = std::env::temp_dir().join(format!("anicraft-bridge-live-{}", std::process::id())); + std::fs::create_dir_all(&dir).unwrap(); + let file = dir.join(CONTROL_FILE); + let app = App::start(Session::default()); + std::fs::write(&file, ControlFile { port: app.port, token: TOKEN.into(), pid: 1, version: String::new() }.to_json().to_string()).unwrap(); + let addr = SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::LOCALHOST, app.port)); + let mut b = Bridge::with_token_file(addr, Some(file.clone())); + let r = b.call("anicraft_run", &json!({"command": "draw.rect", "params": {"x": 0, "y": 0, "w": 9, "h": 9}})).unwrap(); + assert_eq!(r["isError"], false, "{r}"); + assert_eq!(b.call("anicraft_document", &json!({})).unwrap()["isError"], false); + assert_eq!(app.session().visible_elements().len(), 1, "the edit landed in the app's session"); + // The app's frame loop is gone: the call fails (as an error the assistant reads), never + // silently. + let r = b.call("anicraft_run", &json!({"command": "draw.rect", "params": {"x": 0, "y": 0, "w": 9, "h": 9}})); + assert!(r.as_ref().map_or(true, |v| v["isError"] == true), "{r:?}"); + let _ = std::fs::remove_dir_all(&dir); +} diff --git a/crates/cli/src/lib.rs b/crates/cli/src/lib.rs index cb9ef155..7f8c6706 100644 --- a/crates/cli/src/lib.rs +++ b/crates/cli/src/lib.rs @@ -2,6 +2,7 @@ //! server (`mcp`). Every operation goes through the engine's command registry. #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] +pub mod control; pub mod mcp; use anicraft_engine::{Session, commands, format}; @@ -33,6 +34,9 @@ USAGE: {\"id\":1,\"cmd\":\"draw.rect\",\"params\":{\"x\":10,\"y\":10,\"w\":50,\"h\":50}} anicraft-cli mcp [file|--sample] Model Context Protocol server on stdin/stdout, for AI assistants (see docs/mcp.md) + anicraft-cli mcp --bridge the same tools, acting live on the AniCraft window + started with `anicraft --control ` + (docs/control-protocol.md) anicraft-cli --version --plugins loads the WebAssembly plug-ins in a folder first (also the @@ -241,6 +245,16 @@ pub fn run(argv: &[String]) -> Result { Ok(String::new()) } "mcp" => { + if let Some(target) = a.flag("bridge") { + if src.is_some() || a.flag("plugins").is_some() { + return Err("mcp --bridge acts on the open AniCraft window: it takes no file or --plugins".into()); + } + let mut b = control::Bridge::new(control::parse_bridge_target(target)?); + let stdin = std::io::stdin(); + let mut stdout = std::io::stdout(); + mcp::serve(&mut b, stdin.lock(), &mut stdout).map_err(|e| e.to_string())?; + return Ok(String::new()); + } let mut s = session(&a, src)?; let stdin = std::io::stdin(); let mut stdout = std::io::stdout(); diff --git a/crates/cli/src/mcp.rs b/crates/cli/src/mcp.rs index 44e3543e..809922e0 100644 --- a/crates/cli/src/mcp.rs +++ b/crates/cli/src/mcp.rs @@ -6,6 +6,10 @@ //! frame as a picture. Everything still goes through `Session::execute`, so undo, validation //! and the confirmation tiers (ADR 0004: `"confirm": true` before irreversible loss) apply to //! an assistant exactly as to the app. +//! +//! The same tools drive the desktop app live (ADR 0070): the app runs [`call_tool`] on its own +//! session for requests from its control port, and `anicraft-cli mcp --bridge ` is this +//! server with a [`Backend`] that forwards each tool call there (`crate::control`). use anicraft_engine::{Session, commands}; use serde_json::{Value, json}; @@ -20,7 +24,8 @@ const MAX_PICTURE_EDGE: f32 = 2048.0; /// Most steps in one `anicraft_run_script` call. const MAX_STEPS: usize = 10_000; -const INSTRUCTIONS: &str = "AniCraft is a 2D animation studio. Every edit is a command: call \ +/// The headless server's instructions (an in-process document no one sees). +pub const INSTRUCTIONS: &str = "AniCraft is a 2D animation studio. Every edit is a command: call \ anicraft_commands to find one (filter by words such as 'tween' or 'export'), then anicraft_run \ with its id and params, or anicraft_run_script for several in order. Frames in params are \ 0-based. Commands act on the current scene, layer, frame and selection, which anicraft_document \ @@ -28,7 +33,8 @@ reports. Use anicraft_render to see a frame. Edits can be undone with edit.undo. would lose work or replace a file refuse until params include \"confirm\": true; ask the person \ before confirming."; -fn tools() -> Value { +/// The tools, as `tools/list` returns them. The desktop app's control port lists the same. +pub fn tools() -> Value { json!([ { "name": "anicraft_commands", @@ -95,21 +101,46 @@ fn error(id: Value, code: i64, message: impl Into) -> Value { json!({"jsonrpc": "2.0", "id": id, "error": {"code": code, "message": message.into()}}) } -fn text_result(v: &Value, is_error: bool) -> Value { +/// A tool result holding `v` as text (pretty JSON unless it is a string). +pub fn text_result(v: &Value, is_error: bool) -> Value { let text = if let Value::String(s) = v { s.clone() } else { serde_json::to_string_pretty(v).unwrap_or_default() }; json!({"content": [{"type": "text", "text": text}], "isError": is_error}) } +/// Where tools run: a session, and how a command runs on it. The headless server uses the +/// [`Session`] itself; the desktop app runs commands through its own follow-up (the status +/// line, the view a new document resets), as for the person's own edits. +pub trait Host { + fn session(&self) -> &Session; + /// Runs one command; the error is the engine's message. + fn execute(&mut self, id: &str, params: &Value) -> Result; +} + +impl Host for Session { + fn session(&self) -> &Session { + self + } + fn execute(&mut self, id: &str, params: &Value) -> Result { + Session::execute(self, id, params).map_err(|e| e.to_string()) + } +} + +/// Whether a tool can change the document (the app holds these back while the person is in +/// the middle of a drag or typing, so the two edits never share an undo step). +pub fn tool_changes_document(name: &str) -> bool { + !matches!(name, "anicraft_commands" | "anicraft_document" | "anicraft_render") +} + /// Runs one tool. Tool failures are results with `isError` (so the assistant can read and /// correct them); only malformed calls are protocol errors. -fn call_tool(s: &mut Session, name: &str, args: &Value) -> Result { - let run = |s: &mut Session, step: &Value| -> Result { +pub fn call_tool(h: &mut H, name: &str, args: &Value) -> Result { + let run = |h: &mut H, step: &Value| -> Result { let id = step.get("command").and_then(Value::as_str).ok_or("missing \"command\"")?; let params = step.get("params").cloned().unwrap_or_else(|| json!({})); if !params.is_object() { return Err(format!("{id}: \"params\" must be an object")); } - s.execute(id, ¶ms).map_err(|e| format!("{id}: {e}")) + h.execute(id, ¶ms).map_err(|e| format!("{id}: {e}")) }; Ok(match name { "anicraft_commands" => { @@ -125,8 +156,11 @@ fn call_tool(s: &mut Session, name: &str, args: &Value) -> Result .collect(); text_result(&Value::Array(list), false) } - "anicraft_run" => match run(s, args) { - Ok(v) => text_result(&json!({"result": v, "revision": s.revision, "frame": s.frame, "scene": s.scene}), false), + "anicraft_run" => match run(h, args) { + Ok(v) => { + let s = h.session(); + text_result(&json!({"result": v, "revision": s.revision, "frame": s.frame, "scene": s.scene}), false) + } Err(e) => text_result(&Value::String(e), true), }, "anicraft_run_script" => { @@ -136,15 +170,17 @@ fn call_tool(s: &mut Session, name: &str, args: &Value) -> Result } let mut results = Vec::with_capacity(steps.len()); for (i, step) in steps.iter().enumerate() { - match run(s, step) { + match run(h, step) { Ok(v) => results.push(v), Err(e) => return Ok(text_result(&json!({"failed_step": i + 1, "error": e, "done": results}), true)), } } + let s = h.session(); text_result(&json!({"results": results, "revision": s.revision, "frame": s.frame}), false) } - "anicraft_document" => text_result(&s.info(), false), + "anicraft_document" => text_result(&h.session().info(), false), "anicraft_render" => { + let s = h.session(); let frame = match args.get("frame") { None | Some(Value::Null) => s.frame, Some(v) => v.as_u64().and_then(|f| u32::try_from(f).ok()).ok_or("\"frame\" must be a whole number from 0")?, @@ -173,8 +209,26 @@ fn call_tool(s: &mut Session, name: &str, args: &Value) -> Result }) } +/// What answers `tools/call`: the in-process session (headless), or the desktop app through +/// its control port (`--bridge`, `crate::control::Bridge`). +pub trait Backend { + /// The `instructions` the server gives the assistant at `initialize`. + fn instructions(&self) -> &'static str; + /// A `tools/call` result, or the message of a protocol error (a malformed call). + fn call(&mut self, name: &str, args: &Value) -> Result; +} + +impl Backend for Session { + fn instructions(&self) -> &'static str { + INSTRUCTIONS + } + fn call(&mut self, name: &str, args: &Value) -> Result { + call_tool(self, name, args) + } +} + /// Answers one JSON-RPC message; `None` for notifications (and responses), which get no reply. -pub fn handle(s: &mut Session, line: &str) -> Option { +pub fn handle(s: &mut B, line: &str) -> Option { let msg: Value = match serde_json::from_str(line.trim_start_matches('\u{feff}')) { Ok(v) => v, Err(e) => return Some(error(Value::Null, -32700, format!("parse error: {e}"))), @@ -198,7 +252,7 @@ pub fn handle(s: &mut Session, line: &str) -> Option { "protocolVersion": version, "capabilities": {"tools": {"listChanged": false}}, "serverInfo": {"name": "anicraft", "title": "AniCraft", "version": env!("CARGO_PKG_VERSION")}, - "instructions": INSTRUCTIONS + "instructions": s.instructions() }) } "ping" => json!({}), @@ -206,7 +260,7 @@ pub fn handle(s: &mut Session, line: &str) -> Option { "tools/call" => { let Some(name) = params.get("name").and_then(Value::as_str) else { return Some(error(id, -32602, "tools/call needs a tool \"name\"")) }; let args = params.get("arguments").cloned().unwrap_or_else(|| json!({})); - match call_tool(s, name, &args) { + match s.call(name, &args) { Ok(v) => v, Err(e) => return Some(error(id, -32602, e)), } @@ -218,7 +272,7 @@ pub fn handle(s: &mut Session, line: &str) -> Option { /// The stdio loop: one message per line in, one reply per line out, until stdin closes. /// Nothing but protocol messages is written to `out` (logs would corrupt the stream). -pub fn serve(s: &mut Session, input: R, out: &mut W) -> std::io::Result<()> { +pub fn serve(s: &mut B, input: R, out: &mut W) -> std::io::Result<()> { for line in input.lines() { let line = line?; if line.trim().is_empty() { diff --git a/docs/adr/0070-live-control-port.md b/docs/adr/0070-live-control-port.md new file mode 100644 index 00000000..44637065 --- /dev/null +++ b/docs/adr/0070-live-control-port.md @@ -0,0 +1,99 @@ +# ADR 0070: A live control port, so assistants edit the open window + +* Status: accepted (2026-11-12) +* Relates to: ADR 0004 (destructive actions), ADR 0005 (typography), ADR 0006 (platforms), + ADR 0040 (interface languages), `docs/mcp.md`, `docs/control-protocol.md` + +## Context + +`anicraft-cli mcp` gives AI assistants the engine's commands as five MCP tools, but it edits a +document inside its own process, with no window. To see the result the person saves, then opens +the file in the app. Every edit is invisible until then, and the assistant and the person can +never work on the same document at once. + +The sister apps (VectorCraft, CadCraft, FilmCraft, EffectCraft) already let an assistant drive the +open window through a TCP port on `127.0.0.1`, with a line-per-message JSON protocol and an MCP +"bridge" that forwards to it. AniCraft should behave the same way. + +One lesson from FilmCraft: its token was an environment variable, which a desktop shortcut's +process received and an MCP server started by the assistant's desktop app did not. Authentication +must not depend on an environment variable reaching two unrelated processes. + +## Decision + +1. **`anicraft --control `** (also `ANICRAFT_CONTROL_PORT`; the flag wins) opens a control + port on `127.0.0.1` only. 9878 is the convention (after EffectCraft's 9877). A bad port is an + error before any window opens. If the port can't be opened (in use), the window opens anyway + and the status bar says why. +2. **The protocol is small** (`docs/control-protocol.md`): one JSON object per line each way, + persistent connections, answered in order. Methods: `hello`, `tools.list`, `tools.call`. + Replies are `{"id", "ok": true, "result"}` or `{"id", "ok": false, "error"}`. +3. **One dispatcher for live and headless.** The app depends on the `anicraft-cli` library and + runs its `mcp::call_tool` and `mcp::tools` on the window's session. `call_tool` is generic over + a small `Host` trait (the session, and how a command runs), so the app runs commands through + its own follow-up (`App::announce`: the status line, the view a new document resets, Open + Recent), as for the person's own edits. + + *Considered:* a new crate for the dispatcher, used by both. It would have to be L4 (it needs + the engine and the renderer), and the CLI (L4) may not depend on a crate in its own layer, so + the CLI would have to move up beside the shell. The shell (L5) depending on the CLI library + (L4) fits the layering as it is, adds no crate, and the CLI library has no dependency the shell + doesn't already have (except `getrandom`, below). The CLI's library already was the MCP server; + it now also holds the control port's protocol, its listener threads and the bridge client + (`crates/cli/src/control.rs`), none of which touches the UI toolkit, so they are tested there. +4. **Threads, and the frame.** One listener thread and one thread per connection (at most 16). A + tool call goes to the UI thread through a channel with a reply sender; the connection thread + wakes the window (`request_repaint`). The frame loop runs waiting calls at the start of the + frame, before anything draws, so their edits show in the same frame (AGENTS.md "edits are + live"). The window never takes focus. An edit made behind the start screen (ADR 0059) + closes it, so the person sees the document change. +5. **The person's own gestures.** An edit from a tool must not join the person's undo step. While + the person is dragging (pointer held, a stage drag, or a plug-in dialog previewing), calls that + can change the document wait (calls that only read don't). A call that waited 60 s is refused + without running, and the client is told so. An open gesture that is only typing (a property + field still focused) is committed first, as its own undo step, as clicking elsewhere would do; + waiting for that could block an assistant indefinitely. + + *Considered:* committing the gesture mid-drag. The rest of the drag would then record one undo + step per frame, so we wait instead. +6. **Authentication: a token file, no setup.** Each run with `--control` makes a fresh 32-byte + token from the operating system's random numbers (`getrandom`, MIT OR Apache-2.0, already in + the tree) and writes `control.json` (`port`, `token`, `pid`, `version`) to the AniCraft settings + folder, owner-only on macOS and Linux (`%APPDATA%` is already private on Windows). It is + replaced at start and removed on exit if it still holds this run's token. Every request carries + the token; a missing or wrong token is refused and the connection closed before anything runs. + `ANICRAFT_CONTROL_TOKEN`, when set, is the token on both sides (CI, power users). + + The CLI can't use the shell's `platform::config_dir`, so it has its own copy of the folder rule + (`control::settings_dir`) and a shell test keeps the two equal. + + *Considered:* no authentication (VectorCraft, CadCraft, EffectCraft). Any local process, and a + web page able to reach localhost, could then edit and save files as the person. *Considered:* + an environment-variable token only (FilmCraft): see Context. +7. **Hardening, as in the sister apps.** Every line must be a JSON object with a string `method`; + anything else gets one error line and the connection closes. That also refuses a web page's + `fetch` to localhost, which starts with an HTTP request line. Lines are capped at 4 MiB. Writes + time out after 10 s so a client that stops reading can't hold a thread. +8. **Safety rules unchanged.** Calls run through `Session::execute`, so `"confirm": true` (ADR 0004) + is needed exactly as headless, unsaved-work guards and crash recovery see the edits as the + person's, and every edit undoes with Ctrl+Z. +9. **`anicraft-cli mcp --bridge `** is the MCP server with a backend that + forwards `tools/call` to the app; `initialize` and `tools/list` are answered locally (the same + tool list), so the server starts and lists its tools before AniCraft is open. It connects on + the first call and returns an error that says how to start the app when it can't. It reconnects + after a break (an app that quit is noticed before the next request is sent). An edit whose reply + was lost is never sent again (the app may have made it); a call that only reads is tried once + more. Hosts other than this computer are refused. +10. **Visible.** While the port is open the status bar says "Remote control on (port N)" (through + `tr!` and `theme::Type`), with a tooltip saying what that means. + +## Consequences + +* The shell now builds the CLI library (small; nothing new for the web build, which leaves the + control port out). +* The tool behaviour can't drift between live and headless: one function serves both, and a test + checks that a call through the port answers as `call_tool` does. +* Remote edits arrive at most once per frame batch; a long `anicraft_run_script` blocks the window + while it runs, as a long menu command would. +* Not yet: a screenshot tool that returns the window itself (the app already captures itself for + `--screenshot`). diff --git a/docs/adr/README.md b/docs/adr/README.md index 8a35fed1..65918325 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -23,3 +23,4 @@ has to renumber because another PR merged first. | Number | Pull request | Topic | |---|---|---| | 0037 | #38 (outside contribution) | Interface languages | +| 0070 | feat/live-control | Live control port | diff --git a/docs/control-protocol.md b/docs/control-protocol.md new file mode 100644 index 00000000..5e0fec7f --- /dev/null +++ b/docs/control-protocol.md @@ -0,0 +1,103 @@ +# The live control port + +`anicraft --control ` opens the AniCraft window as usual and also listens on a port on this +computer, so an assistant (or a script) can edit the open document while you watch. Every edit +appears in the window at once and undoes with Ctrl+Z, like your own. The status bar says +"Remote control on (port N)" while it is open. ADR 0070 records the design. + +Most people never speak this protocol themselves: AI assistants reach it through +`anicraft-cli mcp --bridge ` (see `docs/mcp.md`). + +```sh +anicraft --control 9878 # 9878 by convention +ANICRAFT_CONTROL_PORT=9878 anicraft # the same; --control wins over the variable +``` + +## Transport + +* TCP on `127.0.0.1` only. +* One JSON object per line (UTF-8, `\n`; a `\r` before it is ignored), each way. +* Connections stay open; requests on one connection are answered in order. + +## Authentication + +Each run makes a fresh token: 64 hex digits from the operating system's random numbers. The app +writes it to `control.json` in AniCraft's settings folder: + +| System | File | +|---|---| +| Windows | `%APPDATA%\AniCraft\control.json` | +| macOS | `~/Library/Application Support/AniCraft/control.json` | +| Linux | `$XDG_CONFIG_HOME/anicraft/control.json` (default `~/.config/anicraft/`) | + +```json +{"port": 9878, "token": "3f1c…", "pid": 12345, "version": "0.2.1"} +``` + +On macOS and Linux the file is readable only by you; on Windows the settings folder already is. +It is replaced when AniCraft starts with `--control` and removed when it closes. A program running +as you finds the token there, with nothing to copy into its settings. + +If `ANICRAFT_CONTROL_TOKEN` is set, it is the token instead (set it for both the app and the +client: CI, power users). + +Every request carries `"token"`. A missing or wrong token gets an error and the connection +closes before anything runs. + +## Requests and replies + +```json +{"id": 1, "token": "…", "method": "hello"} +{"id": 1, "ok": true, "result": {"app": "AniCraft", "version": "0.2.1", "protocol": 1}} +``` + +`id` is any JSON value and comes back as it was. A reply is `{"id", "ok": true, "result"}` or +`{"id", "ok": false, "error": "message"}`. + +| Method | Params | Result | +|---|---|---| +| `hello` | | `{app, version, protocol}` | +| `tools.list` | | the tools, exactly as MCP `tools/list` lists them (`docs/mcp.md`) | +| `tools.call` | `{name, arguments}` | exactly what MCP `tools/call` returns: `{content: […], isError}` | + +`tools.call` runs the same code as the headless MCP server. A tool that fails (a command's error) +is a result with `"isError": true`; a malformed call (an unknown tool, a missing `name`) is an +`"ok": false` reply. + +```json +{"id": 2, "token": "…", "method": "tools.call", "params": {"name": "anicraft_run", "arguments": {"command": "draw.rect", "params": {"x": 10, "y": 10, "w": 50, "h": 50}}}} +{"id": 2, "ok": true, "result": {"content": [{"type": "text", "text": "{\"frame\": 0, \"result\": {…}, \"revision\": 3, \"scene\": 0}"}], "isError": false}} +``` + +## When calls run + +The window runs calls at the start of a frame, so an edit shows in that frame. It never takes +keyboard focus and doesn't need to be the front window. An edit made while the start screen is showing closes it, so you see +the document it changed. + +While you are dragging (or a plug-in dialog is previewing), calls that could change the document +wait until you let go, so your drag and the assistant's edit stay separate undo steps. Calls that +only read run at once. If you were typing in a field, your change is kept as its own undo step +first. A call that waited 60 seconds is not run, and its reply says so. + +Commands that would lose work or replace a file still need `"confirm": true` (ADR 0004). + +## Limits + +| | | +|---|---| +| Line length | 4 MiB; a longer line gets an error and the connection closes | +| Connections | 16 at once; another gets an error line and is closed | +| Waiting | 60 s per call | +| First line | must be a JSON object with a string `"method"`, or the connection closes (this also refuses a web page's request to localhost) | + +## Trying it by hand + +With AniCraft open with `--control 9878`, in PowerShell: + +```powershell +$t = (Get-Content "$env:APPDATA\AniCraft\control.json" | ConvertFrom-Json).token +$c = New-Object Net.Sockets.TcpClient 127.0.0.1, 9878 +$w = New-Object IO.StreamWriter $c.GetStream(); $r = New-Object IO.StreamReader $c.GetStream() +$w.WriteLine("{""id"":1,""token"":""$t"",""method"":""hello""}"); $w.Flush(); $r.ReadLine() +``` diff --git a/docs/mcp.md b/docs/mcp.md index ce1a3be1..b3f8a088 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -8,8 +8,22 @@ look at frames and export through the same commands the app uses. anicraft-cli mcp # a new, empty document anicraft-cli mcp scene.anicraft # open a document anicraft-cli mcp --sample # the sample animation +anicraft-cli mcp --bridge 9878 # the AniCraft window you have open (below) ``` +## Headless or live + +Without `--bridge` the server edits a document of its own, with no window: good for pipelines and +batch work. Save it (`file.save`) to keep the result. + +With `--bridge ` the same tools act on the AniCraft window you have open, started with +`anicraft --control `: every edit appears there at once, and Ctrl+Z undoes it +(`docs/control-protocol.md`, ADR 0070). The server starts even when AniCraft isn't open (an +assistant starts its servers when it starts) and connects on the first tool call; until AniCraft is +open with remote control, the tools answer with how to start it. Close and reopen AniCraft whenever +you like: the next call reconnects, with no need to restart the assistant. It finds the run's token +in `control.json` in AniCraft's settings folder, so there is nothing to copy. + The server talks MCP's stdio transport: JSON-RPC 2.0, one message per line on stdin and stdout. It speaks protocol revisions 2025-06-18, 2025-03-26 and 2024-11-05. @@ -28,6 +42,19 @@ Most clients take a server entry like this one (use the full path to `anicraft-c } ``` +For live editing, start AniCraft with `--control 9878` (a desktop shortcut is handy) and use: + +```json +{ + "mcpServers": { + "anicraft": { + "command": "C:\\path\\to\\anicraft-cli.exe", + "args": ["mcp", "--bridge", "9878"] + } + } +} +``` + ## Tools | Tool | What it does | @@ -54,3 +81,6 @@ timeline). save, import, export), as with the CLI. Only connect clients you trust with those files. * A failing command comes back as a tool result marked as an error, so the assistant can read the message and try again; it never stops the server. +* Live (`--bridge`): an edit whose answer was lost (AniCraft closed mid-call) is never sent again, + since it may have been made; the assistant is told to check with `anicraft_document`. While you + are dragging, the assistant's edits wait until you let go, so the two stay separate undo steps. diff --git a/docs/roadmap.md b/docs/roadmap.md index 6161a6c3..f352c14a 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -14,7 +14,7 @@ milestone ends with a green tree: build, tests, clippy, a `--screenshot` check a | Drawing | Selection (click, shift-add, marquee, drag-move, arrow nudge; **across layers**, ADR 0044: a selection holds artwork on several visible, unlocked layers, the timeline marks them, Properties shows mixed values), **Free Transform (Q)**: scale from corner/edge handles (Shift proportional, Alt from centre), rotate outside corners (Shift snaps 15°), move; one undo step per drag. Rectangle (corner radius), oval, PolyStar, line (45° snap), hand, zoom. **Pen (P)**: click for corners, drag for smooth handles (Alt breaks them), close on the first point, Enter/Esc/last-point click finishes, Backspace takes back a point; one undo step per path. **Pencil (Shift+Y)**: Smooth (Schneider curve fitting with corner detection), Straighten and Ink modes, smoothing relative to the screen. **Subselection (A)**: anchors and handles on selected shapes, drag points/handles (anchors bring their handles; one undo step per drag), point marquee, double-click an edge to add a point, Delete removes points, right-click Make Smooth/Corner; closed shapes' start point and closing edge edit like any other. **Cut/Copy/Paste in Center/Paste in Place** (the clipboard carries symbols across documents). **Rotate 90° CW/CCW, Flip H/V. Align** left/centre/right/top/middle/bottom (Ctrl+Alt+1…6; a single element aligns to the stage) and distribute. Convert to symbol / break apart; arrange; duplicate. Headless: `draw.path`, `draw.freehand`, `path.move_points/add_point/delete_points/convert_point`. **Paint Bucket (K)**: click a fill to recolour it, or inside an outline (one shape or several) to fill the enclosed area; gap size None/Small/Medium/Large closes openings; the fill is traced and curve-fitted into a new shape placed under its lines; open areas say so instead of flooding. **Ink Bottle (S)**: gives the clicked shape the current stroke. Headless: `paint.bucket`, `paint.ink`. Tool options show first in Properties while a drawing tool is active. **Text (T)** (ADR 0012): click to type on the stage, click or double-click text to edit it; font (installed families, plus the embedded Inter), size, colour, bold, italic, alignment, letter/line spacing, wrap width; the last style is kept for new text; laid out by `anicraft-text` (`fontdb` discovery, `harfrust` shaping, `skrifa` outlines) and stored as outlines with the source, so rendering never needs the font; Break Apart makes a shape. **Variable-width strokes** (ADR 0018): a stroke's width varies along it through width points (position by arc length, a width on each side as a factor of the stroke width, smooth monotone interpolation); built-in profiles (Uniform, Taper both ends, Taper start, Taper end, Bulge, Pinch) in Properties › Width with a picture of each, and in the drawing tools' options for new strokes; the **Width tool (U)**: hover a stroke to see its width points, drag a handle to widen or narrow (Alt: one side), drag the dot to slide a point, drag anywhere on the stroke to add one, Delete removes; one undo step per drag; rendered by the oracle as trapezoids with outer round joins and cross-section caps, written by SVG and Lottie export as the same filled outlines; shape tweens blend profiles; `.anicraft` keeps them (older files open as uniform). Headless: `stroke.set_profile`, `stroke.set_width_point`, `stroke.delete_width_point`, `stroke.width_at`, `profile` on `element.set_stroke`, the drawing commands and `paint.ink`. Not yet: width data from or to Animate files, saved custom profiles, pressure. **Stroke styles** (ADR 0046): Properties › Style (Solid, Dashed with dash and gap, Dotted with spacing), Cap (None, Round, Square), Join (Miter, Round, Bevel) and Miter limit, also in the drawing tools' options for new strokes; drawn exactly by the oracle (butt and square caps, miters bevelled past the limit, dashes by arc length restarting per subpath, round dots, dashes keeping a width profile's widths; sub-pixel patterns solid and faded) and so by the GPU stage; the Ink Bottle carries the style and the Eyedropper picks it; merge drawing keeps it on cut pieces; shape tweens blend miter limits and dash lengths; SVG, HTML canvas and Lottie export write it. Headless: `stroke.set_style`, and `cap`, `join`, `miter`, `style`, `dash`, `dash_offset`, `dot_spacing` on `element.set_stroke`, the drawing commands and `paint.ink`. Not yet: Animate's ragged, stipple and hatched styles, multi-dash patterns in Properties (kept and editable by command), stroke scale modes and hairlines. **Merge drawing** (ADR 0031, first slice): with Object Drawing (J) off, the editor's default, the shape tools, Pen and Pencil draw raw strokes and fills that cut and join the raw shapes they touch (a fill on top replaces what it covers or joins the same colour, lines cut each other and the fills they cross, a fill hides the lines under it, points within 0.2 px are one; exact Bézier pieces, `anicraft_geom::planar`); one element per fill region and stroke run, selected with Animate's dot pattern; double-click selects connected strokes, or a fill with its outline; a dragged or nudged raw shape merges where it lands; arrows move 1 screen pixel (Shift 10). Headless: `object` on the drawing commands (scripts draw objects by default), `draw.object_drawing`, `draw.drop`, `element.select_connected`. **Selection tool on raw shapes** (ADR 0041): drag an unselected segment or fill edge to bend it through the pointer (every shape sharing the edge bends with it), an unselected corner or end to move it with every raw shape that shares it, a fill to move only that fill; points and selections snap to points, strokes and fill edges within 10 screen px (snap ring), and arrow nudges join ends within 0.2 px at their midpoint or onto a line that stays put; a corner or curve mark by the pointer shows what a drag does; the marquee selects the parts of raw fills and strokes under it, cut at its edges (taken back if nothing uses them, no undo step), and objects wholly inside; each drag one undo step, merged on release. Headless: `path.bend_segment`, `raw.move_point`, `raw.select_rect`, `raw.merge`, `raw.hit`, `snap` on `element.translate`. **Subselection on raw shapes and merging everywhere** (ADR 0042): with Subselection (A), a click on a raw line or fill shows the anchors of everything connected to it (once per shared point; hollow, selected ones solid) and the handles of the selected anchors' curves and of the clicked edge; drag an anchor to move it with the other selected ones and every shape on them, a handle to change the curve in every shape that has the edge, a line or fill to move everything connected; Shift adds or removes anchors; the marquee takes whole shapes on the active layer and selects the anchors inside; arrows nudge 1 screen px (Shift 10); one undo step per gesture, merged on release. **Snap to Objects** (View › Snapping, a magnet under the tools, the selection tools' options) switches the Selection and Subselection tools' snapping. The Paint Bucket's raw fills are exact (up to the lines and fill edges, from the planar merge) and join fills of their colour; pasted raw shapes cut what they land on; raw shapes from Animate files open raw and merged; gradient and bitmap fills take part in the merge. Headless: `raw.subselect`, `raw.subselect_rect`, `raw.points`, `raw.move_handle`, `with` on `raw.move_point`, `draw.snap_to_objects`, `object` on `paint.bucket`. Not yet: width profiles in the merge. **Raw points and symbols in place** (ADR 0045): add a point on a raw edge (Pen Alt-click, Subselection double-click; every shape on the edge gets it, the curve unchanged), delete raw points (Delete; the shapes on each are joined across it so the drawing stays connected; points where three edges meet are kept), Make Smooth / Corner on raw points, smooth handle pairs (Alt breaks them; drawing objects too); the Line, Rectangle, Oval, PolyStar and Pen tools snap their points within 10 screen px (Snap to Objects, Ctrl+Shift+/); a double-click on an instance (or Ctrl+E, or a double-click in the Library) opens the symbol in place, the stage dimmed around it, the edit bar showing the path back, and every tool and command works on its timeline. Headless: `raw.add_point`, `raw.delete_points`, `raw.convert_points`, `draw.snap`, `smooth` on `raw.move_handle` and `path.move_points`, `symbol.edit`, `symbol.exit`. Not yet: rotated instances in place (they open upright). Onion skin and Edit Multiple Frames work inside a symbol since ADR 0051. **Brush (B)** (ADR 0033, first slice): paints filled shapes in the fill colour, the exact area the tip sweeps (a distance field traced and fitted with cubics); round or square tip with size, angle and roundness (oval and flat calligraphic tips), pen pressure from a tablet (10–100 % of the size; a mouse paints full size), smoothing relative to the screen, Paint Normal, Paint Fills and Paint Behind; a raw shape that merges with the drawing, or a drawing object with Object Drawing on; a click paints a dab; live preview while dragging; `[` and `]` change the size; one undo step per stroke. Headless: `draw.brush`. Not yet: Paint Selection and Paint Inside. **Brush library, pressure curves and the Paint Brush (Y)** (ADR 0068, first slice): Window › Brush Library with seven built-in brushes made only of parameters (Pencil, Ink Pen, Flat Calligraphy, Round Taper, Marker, Chalk with a deterministic worn edge, Dotted stamps), each with a stroke preview drawn by the renderer; brushes of your own saved by name in your preferences, renamed, deleted (asks first) and moved between computers as a JSON brush set; a pressure curve editor (Linear, Soft, Firm, or your own points) driving size and, optionally, the stroke's opacity; tapers, dab spacing and a rough edge in Properties; Velocity (mouse speed as pressure, off by default); the Paint Brush draws a width-profiled stroke in the stroke colour that the Width tool edits. Headless: `brush.preset_list/save/rename/delete/export/import`, `preset`, `curve`, `as_stroke` and the shaping params on `draw.brush`. Not yet: pen tilt (egui doesn't report it), opacity varying along a stroke, textured or art brushes, Eraser presets and pressure. **Eraser (E)** (ADR 0034, first slice): sweeps the Brush's tip and takes what it covers out of the raw shapes on the active layer (the sweep is a fill in the planar merge that comes out empty); Erase Normal, Erase Fills, Erase Lines, Erase Selected Fills and Erase Inside; the Faucet deletes a whole fill or line with a click; drawing objects, symbols and text are kept; a stroke that erases nothing leaves no undo step; live preview, `[` and `]` sizes, one undo step per stroke; double-clicking the tool (or Erase Everything… in its options) clears the visible, unlocked layers at this frame after asking. **Eyedropper (I)** (first slice): a click on a fill picks its paint (solid, or a gradient or bitmap kept where it is on the stage, as Lock Fill) into the fill swatch, a click on a line picks its colour, width and profile; with shapes selected it applies the style to them; then it becomes the Paint Bucket or the Ink Bottle; Shift-click picks into the other swatch only. Headless: `draw.erase`, `draw.faucet`, `draw.erase_all`, `paint.pick`, `paint.apply_style`. Not yet: erasing inside symbols, erasing width-profiled shapes (gradient fills erase since ADR 0042), eraser pressure, picking a bitmap's pixel colour or text styles, an eyedropper cursor. | | Plug-ins | **WebAssembly plug-ins** (ADR 0017, `docs/plugins.md`): sandboxed modules run by `wasmi` with no imports but the AniCraft ABI (`anicraft.call`/`anicraft.response`: JSON requests that run registry commands, read a compact document view or the active layer's elements, and log); fuel (10⁹ instructions), memory (256 MiB), wall-clock (5 s), request, size and log limits, a fresh instance per run; file, plug-in, undo and clipboard commands refused. `plugin.install/list/run/remove/reload`; a run is atomic and one undo step named after the plug-in. App: **Commands** menu (Plug-ins, Install, Manage, Reload), palette entries, a dialog generated from the manifest's parameters with a live preview; plug-ins load from `/plugins` or `ANICRAFT_PLUGINS`; CLI `--plugins`. Samples in Rust (Star Field, Jitter Selection, guest SDK) in `examples/plugins`. Frame scripts: see Interactivity. Not yet: exporter and easing kinds, background runs with cancel, a binary document view. | | Interactivity | **Frame actions, frame scripts and Test Movie, first slice** (ADR 0024): a typed timeline action IR (`anicraft-actions`: stop, play, go to a frame or label in a scene, next/previous frame and scene, trace, set x/y/alpha/visible/rotation/scale, instance-name target paths) on keyframes and on button and movie clip instances (click, press, release, over, out); a pure, deterministic, budgeted player in `anicraft-doc` (`step(doc, &state, &events)`; movie clip playheads, button Up/Over/Down states with Hit-frame hit tests, script-set properties) drawn by `evaluate_player`, while `evaluate` and exports stay script-free. **Actions panel** (F9: structured lists, targets/labels/scenes picked from the document; movie clip timelines too), instance name and events in Properties, an "a" on keyframes with actions. **Frame scripts** on the plug-in host (`kind: "frame-script"`, entry points, `player`/`action` ops, 20 M instructions per frame shared, no document access). **Test Movie** (Control › Test Movie, Ctrl+Enter): the player at the document frame rate in its own window with the pointer, restart/pause/step and an Output panel. **A window of its own on the desktop** (ADR 0062): sized to the stage at 100 % (smaller to fit the screen), titled with the document, back where it was last (not on Wayland, where the desktop places windows), with the keyboard when it opens; Esc or Ctrl+W (⌘W) closes it, Ctrl+Enter restarts it in place, and the editor's Ctrl/Alt shortcuts work from it; floating inside the editor in the web build, where the system can't open windows (it says so), or by choice in Preferences › Test Movie. Not yet: full screen, zoom in the movie window, remembering its size. Headless: `actions.set/clear/list`, `instance.set_name`, `control.test_movie` (timed pointer events, returns output and state). **HTML canvas export** (ADR 0028, `file.export_html`, File › Export › Export HTML Canvas…): one self-contained page (data, player and drawing code inline; images and sounds embedded) that plays in any browser with canvas 2D; every used timeline baked frame by frame (tweens of every kind exact, identical paths, paints and frames stored once), movie clips, buttons with Hit areas and every action run by `player.js`, a port of the Rust player checked against it step by step in Boa (state, output and display list); masks and fading/blending groups on offscreen layers; Web Audio for Event/Start/Stop/Stream sounds; filters, Subtract/Invert, bitmap tints and plug-in frame scripts reported. **Kept frame scripts** (ADR 0013 tier 1): scripts written in another language (an Animate document's ActionScript) kept verbatim on keyframes with their language, symbol linkage classes and the document class; the Actions panel's **Script** view (monospace editor with line numbers, language, live and undoable), the same "a" marker, Class rows in Properties; `script.set/clear/list/set_class`; **ActionScript timeline subset runs** (ADR 0013 tier 2): a hand-written, bounded lexer and parser (`anicraft_actions::as3`) lower stop/play/go to/next and previous frame and scene on instance-name paths, mouse listeners (click, down, up, roll over and out; named or inline functions, `currentTarget`), `trace` and property settings to the action IR, compiled once per script; anything else is reported with line and column and the script doesn't run (never half-run), `navigateToURL` and the like are ignored and noted; the player keeps listeners per instance, Test Movie's Output says which scripts run and which don't and why, the Script view lists problems in place, the XFL report and `script.list/check` say what runs, and the HTML page runs the same steps (`player.js` checked against the Rust player). **ActionScript small logic** (ADR 0052): scripts compile to a small typed script IR evaluated by the player with fuel (100,000 per script or listener call, 1,000,000 per step; an endless loop or a run-time error stops its script with an Output line and the movie plays on): typed variables (Number, int, uint, Boolean, String, untyped) kept per timeline instance across its frame scripts, expressions as ECMA-262 has them, `if`/`else`, `for`/`while`/`do`, functions with parameters, results and recursion, called from any frame of the same timeline (a timeline-level link step; names that aren't there keep the script from running, said in place), property reads of instances and timelines (`x`, `y`, `alpha`, `visible`, `rotation`, `scaleX/Y`, `currentFrame`, `totalFrames`, `currentLabel`, `mouseX/Y`, `name`), `removeEventListener`, `Event.ENTER_FRAME`, `KeyboardEvent.KEY_DOWN/KEY_UP` on the stage with `e.keyCode`, `e.target`/`e.currentTarget`, seeded `Math.random()`; keyboard in Test Movie and the HTML page, `control.test_movie` key events and `seed`; `player.js` mirrors the evaluator, checked step by step in Boa. Not yet: ActionScript `switch`, `for in`, arrays and objects, string methods, closures, event bubbling, mouse listeners on the stage, ActionScript 1.0/2.0, scripts on instances, filters and keyboard focus in the HTML page, sound actions, keyboard events, variables, persistent script state, masks in hit tests, a separate OS window. **Buttons, complete** (ADR 0057): a button open in place names its frames Up, Over, Down and Hit on the timeline and shows its Hit area translucent over the other states; Test Movie has **Show hit areas**; sounds on its frames play as its state changes. | -| Headless | CLI: info, render, render-seq, **gif**, **apng**, **webp**, commands, exec, run, serve (JSON-lines). **MCP server** (`anicraft-cli mcp`, `docs/mcp.md`): stdio JSON-RPC, protocol 2025-06-18 (and 2025-03-26, 2024-11-05); five tools over the command registry (list, run, run a script, describe the document, render a frame as a PNG picture); confirmation tiers and undo apply as in the app. | +| Headless | CLI: info, render, render-seq, **gif**, **apng**, **webp**, commands, exec, run, serve (JSON-lines). **MCP server** (`anicraft-cli mcp`, `docs/mcp.md`): stdio JSON-RPC, protocol 2025-06-18 (and 2025-03-26, 2024-11-05); five tools over the command registry (list, run, run a script, describe the document, render a frame as a PNG picture); confirmation tiers and undo apply as in the app. **Live control** (ADR 0070, `docs/control-protocol.md`): `anicraft --control ` and `anicraft-cli mcp --bridge ` run the same tools on the open window, with a per-run token in `control.json`. | | Sound | **Audio layers, first slice** (ADR 0020): WAV (own reader), Ogg Vorbis (`lewton`) and MP3 (`nanomp3`) import, bounded and crash-proof; sounds live in the library, stored in `.anicraft` as imported, decoded once in the background. A sound belongs to a keyframe as in Animate (Properties › Sound: name, Sync Event/Start/Stop/Stream, Repeat ×N or Loop); Import to Stage puts one on a new layer spanning its length, Import to Library only adds it, the Library previews, places and deletes sounds. The timeline draws each sound's waveform over its span. Stage playback plays the mix through `cpal` (default feature `sound-output`) and the playhead follows the audio clock; stream sounds resync after a jump and scrubbing plays one-frame snippets. Mixing is pure and sample-exact (`doc::sound::voices` + `audio::mix`, Catmull-Rom resampling between rates). Headless: `sound.place/set/remove/rename/delete`, `file.import_to_library`, **`file.export_audio`** (WAV, 16/24-bit or float, any rate), and Export Video carries the soundtrack (Opus in WebM, AAC in MP4, by the user's ffmpeg). **Second slice** (ADR 0039): each frame sound has an **Effect** (None, Left channel, Right channel, Fade left to right, Fade right to left, Fade in, Fade out, shaped over the time it is heard, or **Custom**: up to 16 volume points per channel in the **Edit Envelope** window, drawn on each channel's waveform; the timeline's waveform follows the envelope). Layers holding sounds get a **Volume** and **Mute** (Properties, and a speaker toggle in the timeline); volumes multiply down through symbols and muted layers are silent in playback and every export. **Sounds inside symbols** play: a graphic's on its own frames mapped to the parent's time (loop mode and first frame apply; streams join mid-way and follow the parent playhead), a movie clip's on a loop from when the instance appeared; in the interactive player and **Test Movie** (which now has sound, the picture keeping time with it) movie clips start theirs as their own timelines reach them. The HTML page carries envelopes, volumes and graphic sounds. Headless: `sound.set {effect, envelope}`, `layer.set_volume`, `layer.toggle_mute`. **Sounds on button frames** (ADR 0057) play in Test Movie and the HTML page as the pointer changes the button's state (Over, Down, and Up and Hit on leaving and release, as the SWF format keeps them; never in the soundtrack); `control.test_movie` lists the sounds it starts. **XFL** brings sounds whose file is in the package (WAV, Ogg, MP3) with the sounds on frames that use them, buttons' included. Not yet: sounds kept only in Animate's own data format (undocumented; reported), sound effects and in/out points from XFL, sound panning beyond the envelope, audio in Lottie, stream sounds that follow go-tos in the HTML page, lossless compression of stored WAVs, latency compensation. | | Files | `.anicraft` JSON load/save (v3, with scenes; v1 and v2 files open as one scene), PNG frame and sequence export, **animated GIF export** (parallel render and quantize, exact frame timing, looping), **animated PNG and animated WebP export** (ADR 0063: full colour and real alpha, transparent or on the stage colour; every frame exactly the renderer's; repeated frames merged into longer delays; later frames only the rectangle that changed (APNG blends opaque changes over, WebP replaces); APNG delays exact fractions of the frame rate, WebP milliseconds that never drift; loop forever, once or N times; File › Export, Publish Settings, the web build's downloads, `anicraft-cli apng`/`webp`; not yet: lossy WebP (no permissive pure-Rust VP8 encoder exists), dispose-to-background frames, palette or RGB APNG for smaller files), **SVG frame export** (from the same evaluated frame as the renderer: stage-space paths, renderer-matched stroke widths, caps, joins and dashes, gradients under `gradientTransform`, colour effects baked in, masks as nested `clipPath`s). **Opens Animate documents** (`.fla`, `.xfl`, XFL folders; ADR 0009; `.fla` archives in every common zip layout, ZIP64 included, and hostile ones refused with a readable error, ADR 0054): stage, first scene, layers, keyframes, labels, classic tweens with ease, shapes (solid/linear/radial fills, strokes), groups, primitives, symbol instances (matrix, alpha, tint, loop, blend mode, all seven filters), library symbols, **shape tweens**, **layer folders** and **mask layers** (masks inside folders too); imported files are untitled so Save never overwrites them; what isn't supported yet is reported after opening. Every scene comes across. **Bitmaps**: library items whose image is in the package as PNG or JPEG (the original in `LIBRARY/`, else the `bin/` data file when it is PNG or JPEG), instances, and bitmap fills with their matrix (twips scale removed; repeating unless clipped); Animate's own bitmap encodings are not public and are reported, not decoded. **Text** (ADR 0014): static, dynamic and input text fields become text blocks laid out by `anicraft-text`, with face (by PostScript name, family, or the family the name suggests; `_sans`/`_serif`/`_typewriter`), size, colour, bold/italic, alignment, letter and line spacing, margins, matrix, fixed width (wraps) or auto-size, and several lines; runs in different styles become one block per run of same-style lines, stacked as in Animate; a line mixing styles takes its main style and is counted; missing families fall back and are named in the report; dynamic/input fields come across as static text (reported). **Shape hints** on shape tweens (a tolerant self-authored `shapeHints` reader, ADR 0023). Colour effects in every style (Brightness, Tint, Advanced, Alpha; ADR 0056), movie clip and button instance names, one-segment custom eases (as cubic Béziers); a symbol without `symbolType` is a movie clip; frame comments aren't labels. Stroke caps, joins and miter limit, dashed and dotted strokes (ADR 0046; ragged, stipple and hatched are drawn solid and reported). Reported rather than silently changed: gradient strokes, repeating/reflecting, focal-point, elliptical and linear-RGB gradients, reverse loop modes, extra tween spins. A self-authored corpus with golden renders covers all of it (ADR 0035). No per-character styles or motion tweens from XFL yet; **frame scripts are kept** verbatim (scenes and every symbol, with the language from the publish settings), with symbol linkage classes and the document class, and the report lists them as kept, not run (ADR 0013 tier 1; scripts on instances and linkage on bitmaps and sounds are reported); **Import to Stage (Ctrl+R) for SVG drawings**: editable shapes on a new layer at the playhead, with groups, use and symbols, transforms, viewBox, styles, opacity and gradients; **clip paths and opaque masks** (ADR 0021) become mask layers in a folder named after the file (clips that cut nothing dropped, clips inside clips intersected exactly when all but one are convex polygons, curves kept), and **text** becomes text blocks, one per text chunk (position, anchor, font family list, size, weight, style, letter spacing, fill), with missing fonts named; stroke caps, joins, miter limits and dashes come across (ADR 0046); soft masks, per-character positions and text on a path are reported, as is anything else unsupported. **Sprite sheet export**: movie frames on one PNG grid (parallel render, columns/padding/scale, transparent or stage background) with a "JSON hash" frame map (rectangles, sizes, per-frame durations). **Video export**: WebM (VP9) or MP4 (H.264) by streaming raw frames, in order and rendered in parallel batches, to the user's own ffmpeg (no encoder bundled; ffmpeg from a parameter, `ANICRAFT_FFMPEG` or the PATH; argument lists, never a shell). **Lottie export** (`file.export_lottie`): frame-accurate rather than re-keyed: each frame is evaluated, artwork that persists (same layer, element, occurrence and path structure) becomes one shape layer with outlines baked to stage space, and whatever changes (outlines, colours, gradient points, stroke width, opacity, masks as layer masks) is written as hold keyframes where it changes; one layer order consistent with every frame (topological); checked against the reference web player (matches the renderer). Reported, not exported: bitmap fills, nested masks (innermost kept), group fades (per shape), stretched radial gradients (circles). **HTML canvas export** (`file.export_html`, ADR 0028): one self-contained web page that plays the movie, buttons and actions included (see Interactivity). **Drops, Open Recent and the start screen** (ADR 0059): files dropped on the window open (documents) or import onto the stage at the drop point on the active layer, or into the Library folder under the pointer, in one undo step (`file.drop`), with a drop highlight; File › Open Recent (10 recent, pinned favourites, missing files greyed with Remove) kept in the preferences; a start screen at launch with New presets (1280 × 720, 1920 × 1080, 1080 × 1080, 1080 × 1920, custom), Open, the sample and recent files with thumbnails captured on save. **Templates, SVG into the Library and drops on the timeline** (ADR 0065): six built-in templates made in code (banners 728 × 90 and 300 × 250, social square 1080 × 1080 at 30 fps, storyboard 16:9 panels, character turnaround, lip-sync mouth chart) with guides on a locked guide layer, on the start screen and File › New from Template; File › Save as Template keeps the document with a picture in the settings folder by category (replacing and deleting confirm); an SVG dropped on or imported to the Library becomes one graphic symbol named after the file, in the folder under the pointer; a sound dropped on a layer's frame goes onto that keyframe, an image or SVG onto that layer in a keyframe made there if needed, one undo step, with a highlight on the cell. Not yet: exact drop positions on the desktop (eframe 0.36 and 0.37 are on winit 0.30, which gives none during a drag; a drop waits for the first pointer move, else lands mid-view), user template descriptions and renaming, several documents at once. **Publish Settings and Publish** (ADR 0060): the formats to publish, with their options and output names, saved in the document; File › Publish (Shift+F12) writes them all in the background with progress, Cancel and one report; presets in Preferences. | | Library | **Library management, first slice** (ADR 0050): nested **folders** (New Folder, rename, drag items and folders in and out, Move to; deleting a folder that holds items asks), **inline rename** (F2 or double-click the name; names unique per folder, case aside), **Duplicate Symbol** (fresh ids, same folder, “Ball copy”), **Swap Symbol** in Properties (keeps transform, colour effect, filters, looping and name), a **use count** column, **Select Unused Items** and **Delete Unused Items** (unused = not reachable from any scene; linkage classes count as used; asks first), deleting used items asks and removes their instances, fills and keyframe sounds, **sort** by name, type, use count or date added, **search** (opens the folders that lead to a match), multiple selection, a **preview** (a symbol's first frame from the oracle, a bitmap as smoothed or not, a sound's waveform with play) and **item properties** (symbol type and linkage class, bitmap **Allow Smoothing**, which the oracle, the GPU stage, SVG and HTML honour). Folders are a side table in the document (older files open flat); XFL import keeps folders and Allow Smoothing. Headless: `library.items/new_folder/rename/move/duplicate/delete/unused/delete_unused/set_smoothing`, `element.swap_symbol`. **Second slice** (ADR 0053): **drag items onto the stage** (symbols and bitmaps land at the pointer on the active layer at the playhead, sounds go onto its keyframe; several at once; one undo step; inside a symbol open for editing too), **Place on Stage** (button, right-click, or Enter) at the centre of the view, **Swap Bitmap** in Properties (a placed bitmap keeps its corner and takes the new size; a bitmap fill keeps its shape), a **Convert to Symbol** dialog with name, type and **folder** that offers the last folder and type again, and **"mixed" on every Properties row** for several elements (Scale, Rotation, Alpha, Symbol, Type, Filters, Blending, Looping, First frame, Fill, Bitmap, Stroke, Width, Style; each row compares only the elements it edits; editing a mixed row sets all, and Type sets every selected instance's symbol). Headless: `library.place {items, x, y}` (and `sound`), `element.swap_bitmap`, `kind` and `folder` on `modify.convert_to_symbol`. **9-slice scaling** (ADR 0055): Enable guides for 9-slice scaling on a symbol (Library or Properties). Scaled instances keep their corners, stretch their edges one way and the centre both ways, and strokes keep their width. Rotation and skew apply after; nested symbols, text and bitmaps scale normally. Guides are dragged as dashed lines while editing the symbol in place, or typed in Properties. The CPU, GPU, SVG and Lottie output all show it, and XFL `scaleGrid*` attributes are imported; guides switched off are kept and come back when switched on (ADR 0057). Not yet: 9-slice in HTML canvas export (scaled as a whole and reported), guides in Library previews, snapping guides. Not yet: shared libraries and importing items from another document, linkage on bitmaps and sounds, bitmap compression, dropping files from the desktop, a picture of the item while dragging, Swap Bitmap on a Library item (every use), mixed text style rows, a Colour Effect row with tint. | diff --git a/src/app.rs b/src/app.rs index 6dccf28e..fb165c7a 100644 --- a/src/app.rs +++ b/src/app.rs @@ -285,6 +285,9 @@ pub use anicraft_engine::doc::LibraryItem; pub struct App { #[cfg(not(target_arch = "wasm32"))] pub(crate) updates: crate::updates::Updates, + /// The live control port, with `--control` (ADR 0070). + #[cfg(not(target_arch = "wasm32"))] + pub(crate) remote: Option, pub s: Session, pub tool: Tool, pub view: StageView, @@ -549,6 +552,8 @@ impl App { let mut app = App { #[cfg(not(target_arch = "wasm32"))] updates: Default::default(), + #[cfg(not(target_arch = "wasm32"))] + remote: None, s: session, tool: Tool::Select, view: StageView { zoom: 1.0, pan: egui::Vec2::ZERO, fit: true, fitted: None }, @@ -2779,6 +2784,8 @@ impl eframe::App for App { self.recovery.finish(&self.s, clean); #[cfg(not(target_arch = "wasm32"))] self.updates.finish(); + #[cfg(not(target_arch = "wasm32"))] + crate::remote::finish(self); } fn ui(&mut self, ui: &mut egui::Ui, _frame: &mut eframe::Frame) { @@ -2798,6 +2805,9 @@ impl App { } } self.handle_screenshot(&ctx); + // An assistant's edits (ADR 0070), before anything draws: they show in this frame. + #[cfg(not(target_arch = "wasm32"))] + crate::remote::poll(self, &ctx); self.poll_font_scan(&ctx); self.follow_system_contrast(&ctx); if let Some(p) = platform::picked_file() { diff --git a/src/main.rs b/src/main.rs index 594d1051..14dc0b90 100644 --- a/src/main.rs +++ b/src/main.rs @@ -3,6 +3,7 @@ //! ```text //! anicraft [file.anicraft] [--screenshot out.png] [--renderer wgpu|gl] [--open ] //! [--theme graphite|high-contrast] [--scale ] [--lang |auto|pseudo] +//! [--control ] //! anicraft --version //! ``` //! `--screenshot` starts normally, draws ~120 frames, saves the window as PNG and exits. @@ -55,6 +56,8 @@ mod platform; mod plugins_ui; mod prefs; mod recent; +#[cfg(not(target_arch = "wasm32"))] +mod remote; mod scale_grid; mod sound; mod shape_hints; @@ -111,7 +114,7 @@ struct Look { } #[cfg(not(target_arch = "wasm32"))] -fn run(renderer: eframe::Renderer, file: Option<&Path>, shot: Option, open: Option, look: Look) -> eframe::Result { +fn run(renderer: eframe::Renderer, file: Option<&Path>, shot: Option, open: Option, look: Look, control: Option) -> eframe::Result { let options = eframe::NativeOptions { viewport: platform::viewport(egui::ViewportBuilder::default().with_title("AniCraft").with_inner_size([1600.0, 940.0]).with_min_inner_size([960.0, 600.0])), renderer, @@ -143,6 +146,10 @@ fn run(renderer: eframe::Renderer, file: Option<&Path>, shot: Option, o start::open(&mut a); } a.preview_look(&cc.egui_ctx, look.theme, look.scale); + // `--control`: an assistant can edit this window live (ADR 0070). + if let Some(port) = control { + remote::start(&mut a, &cc.egui_ctx, port); + } a.open_panel(open.as_deref()); // An imported document says what came across, as opening it from the menu does. if let Some(r) = report { @@ -171,6 +178,8 @@ struct Args { open: Option, renderer: Option, look: Look, + /// `--control `: the live control port (ADR 0070). + control: Option, /// `--version` / `--help`: print and leave. print: Option, } @@ -191,6 +200,8 @@ fn parse_args(args: impl IntoIterator) -> Result { match a.as_str() { "--screenshot" => out.shot = Some(PathBuf::from(args.next().ok_or("--screenshot needs a file name")?)), // i18n-exempt: a console message "--open" => out.open = args.next(), + // i18n-exempt: a console message + "--control" => out.control = Some(anicraft_cli::control::parse_port(&args.next().unwrap_or_default()).map_err(|e| format!("--control: {e}"))?), "--renderer" => out.renderer = args.next(), "--shot-width" => match args.next().and_then(|s| s.parse::().ok()) { Some(w) if (64..=8192).contains(&w) => out.look.shot_width = Some(w), @@ -226,7 +237,7 @@ fn parse_args(args: impl IntoIterator) -> Result { /// `--help` (the console's text, in English). #[cfg(not(target_arch = "wasm32"))] // i18n-exempt: the --help console text -const HELP: &str = "anicraft [file.anicraft|file.fla|file.xfl] [--version] [--screenshot out.png [--shot-width ]] [--renderer wgpu|gl] [--theme graphite|high-contrast] [--scale ] [--lang |auto|pseudo] [--open palette|shortcuts|lastscene|start|drop|droplibrary|select|about|files|confirm|transform|points|merge|rawparts|rawedit|rawsub|rawpoints|rawsnap|symboledit|nineslice|nineslicedit|brush|brushing|brushlibrary|brushcurve|paintbrush|eraser|erasing|eyedropper|pen|frames|span|bucket|tlzoom|tlwide|motion|motionspan|motionpath|motionpoints|motionedit|motionpins|motionpinsspan|hints|hintsend|camera|cameraview|filters|strokes|prefs|licenses|zoom|recovery|plugins|actions|script|scriptproblems|testmovie|testmovieinside|testscript|textfields|testtext|button|testhits|exporthtml|publish|publishreport|publishanim|sound|envelope|library|librarymenu|colour|layerprops|frameview|layercolour|timelinepolish]\n\ +const HELP: &str = "anicraft [file.anicraft|file.fla|file.xfl] [--version] [--screenshot out.png [--shot-width ]] [--renderer wgpu|gl] [--theme graphite|high-contrast] [--scale ] [--lang |auto|pseudo] [--control ] [--open palette|shortcuts|lastscene|start|drop|droplibrary|select|about|files|confirm|transform|points|merge|rawparts|rawedit|rawsub|rawpoints|rawsnap|symboledit|nineslice|nineslicedit|brush|brushing|brushlibrary|brushcurve|paintbrush|eraser|erasing|eyedropper|pen|frames|span|bucket|tlzoom|tlwide|motion|motionspan|motionpath|motionpoints|motionedit|motionpins|motionpinsspan|hints|hintsend|camera|cameraview|filters|strokes|prefs|licenses|zoom|recovery|plugins|actions|script|scriptproblems|testmovie|testmovieinside|testscript|textfields|testtext|button|testhits|exporthtml|publish|publishreport|publishanim|sound|envelope|library|librarymenu|colour|layerprops|frameview|layercolour|timelinepolish]\n\ --renderer force the GPU backend (also ANICRAFT_RENDERER); default wgpu, falling back to OpenGL\n\ --open shows a panel at start (handy with --screenshot for visual checks)\n\ --shot-width scales the screenshot down to this width (the user guide's pictures)\n\ @@ -234,6 +245,8 @@ const HELP: &str = "anicraft [file.anicraft|file.fla|file.xfl] [--version] [--sc --theme the interface palette for this run (not saved)\n\ --scale the interface scale for this run, 75 to 200 (not saved)\n\ --lang the interface language for this run (not saved); pseudo tests the layout\n\ + --control lets an assistant edit this window live through a port on this computer\n\ + (also ANICRAFT_CONTROL_PORT; 9878 by convention; see docs/control-protocol.md)\n\ Headless use: anicraft-cli --help"; #[cfg(not(target_arch = "wasm32"))] @@ -263,7 +276,21 @@ fn main() -> eframe::Result { } None => {} } - let Args { shot, file, open, renderer, look, .. } = args; + let Args { shot, file, open, renderer, look, control, .. } = args; + // ANICRAFT_CONTROL_PORT when there is no --control; a bad port stops here, before a window. + let control = match control { + Some(p) => Some(p), + None => match std::env::var(anicraft_cli::control::PORT_ENV).ok().filter(|v| !v.trim().is_empty()) { + Some(v) => match anicraft_cli::control::parse_port(&v) { + Ok(p) => Some(p), + Err(e) => { + eprintln!("{}: {e}", anicraft_cli::control::PORT_ENV); + std::process::exit(2); + } + }, + None => None, + }, + }; // macOS hands documents over as Apple Events, the one that launched the app included: listen // from before the event loop starts until it ends (ADR 0062). let _documents = platform::listen_for_documents(); @@ -272,10 +299,10 @@ fn main() -> eframe::Result { // on some Linux setups) retry once with OpenGL, unless the user forced a backend. let forced = platform::forced_renderer(renderer.as_deref()); let first = forced.unwrap_or(eframe::Renderer::Wgpu); - match run(first, file.as_deref(), shot.clone(), open.clone(), look.clone()) { + match run(first, file.as_deref(), shot.clone(), open.clone(), look.clone(), control) { Err(e) if forced.is_none() && first == eframe::Renderer::Wgpu => { eprintln!("GPU backend (wgpu) failed to start: {e}. Retrying with OpenGL."); - run(eframe::Renderer::Glow, file.as_deref(), shot, open, look) + run(eframe::Renderer::Glow, file.as_deref(), shot, open, look, control) } other => other, } @@ -305,6 +332,11 @@ mod args_tests { assert_eq!(parse(&["--screenshot", "a.png", "--shot-width", "1200"]).look.shot_width, Some(1200)); assert!(parse_args(["--shot-width".to_string(), "9".to_string()]).is_err()); assert_eq!(parse(&["--version"]).print, Some(Print::Version)); + // `--control ` (ADR 0070): a port from 1 to 65535, or an error before any window. + assert_eq!(parse(&["--control", "9878"]).control, Some(9878)); + for bad in [&["--control"][..], &["--control", "0"], &["--control", "99999"], &["--control", "port"]] { + assert!(parse_args(bad.iter().map(|a| a.to_string())).is_err(), "{bad:?}"); + } // And the file opens: the session starts with it, not the sample. let dir = std::env::temp_dir().join(format!("anicraft-shell-args-{}", std::process::id())); std::fs::create_dir_all(&dir).unwrap(); diff --git a/src/panels.rs b/src/panels.rs index c7a79b2d..eef49bf0 100644 --- a/src/panels.rs +++ b/src/panels.rs @@ -208,6 +208,13 @@ pub fn status_bar(app: &mut App, ui: &mut egui::Ui) { let small = |t: String| text(Type::Data, t).color(T.text_faint); ui.label(small(tr!("undo {steps} · {size} MB", steps = app.s.history().undo_len(), size = format!("{:.1}", app.s.history().bytes() as f32 / (1024.0 * 1024.0))))); ui.add_space(12.0); + // An assistant can edit this window (ADR 0070): always in view while that is so. + #[cfg(not(target_arch = "wasm32"))] + if let Some(port) = crate::remote::port(app) { + ui.label(text(Type::Label, tr!("Remote control on (port {port})", port = port)).color(T.text_faint)) + .on_hover_text(tr!("An assistant can edit this document through a control port on this computer. Its edits appear here at once and undo like your own. Started with --control; close AniCraft to turn it off.")); + ui.add_space(12.0); + } if let Some(a) = crate::autosave::status(app, now) { ui.label(small(a)).on_hover_text(tr!("A recovery copy of your unsaved work. If AniCraft closes unexpectedly, the next start offers it back.")); ui.add_space(12.0); diff --git a/src/platform.rs b/src/platform.rs index d1ca41c5..ab45f471 100644 --- a/src/platform.rs +++ b/src/platform.rs @@ -201,6 +201,31 @@ pub fn recovery_dir() -> Option { } } +/// Writes a file only this user may read (the control port's token, ADR 0070), making its folder +/// first. On Windows the settings folder (%APPDATA%) is already private to the user; elsewhere +/// the file is made owner-only (0600). +#[cfg(not(target_arch = "wasm32"))] +pub fn write_private_file(path: &std::path::Path, contents: &[u8]) -> std::io::Result<()> { + use std::io::Write; + if let Some(dir) = path.parent() { + std::fs::create_dir_all(dir)?; + } + let mut options = std::fs::OpenOptions::new(); + options.write(true).create(true).truncate(true); + #[cfg(unix)] + { + use std::os::unix::fs::{OpenOptionsExt, PermissionsExt}; + options.mode(0o600); + // An older file keeps its mode when opened: tighten it first. + if path.exists() { + std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o600))?; + } + } + let mut f = options.open(path)?; + f.write_all(contents)?; + f.sync_all() +} + /// Whether the recovery folder was chosen explicitly (screenshot runs only touch it then). pub fn recovery_dir_overridden() -> bool { std::env::var_os("ANICRAFT_RECOVERY_DIR").is_some_and(|v| !v.is_empty()) diff --git a/src/remote.rs b/src/remote.rs new file mode 100644 index 00000000..17cc94de --- /dev/null +++ b/src/remote.rs @@ -0,0 +1,143 @@ +//! Remote control (ADR 0070, `docs/control-protocol.md`): `anicraft --control ` opens a +//! control port on this computer, and an assistant (through `anicraft-cli mcp --bridge`) edits +//! the open document live. The port, its threads and the tools are `anicraft_cli::control`'s; +//! this module runs each call on the window's session at the start of a frame, writes the +//! run's token to `control.json` in the settings folder, and removes it on exit. +//! +//! A call that edits waits while the person is dragging (or a plug-in dialog has its preview +//! open), so the two never share an undo step. Typing in a field doesn't hold it back: the +//! person's typed change is committed as its own step first, as clicking elsewhere would. + +use crate::app::{App, Drag}; +use crate::platform; +use anicraft_cli::{control, mcp}; +use anicraft_engine::Session; +use serde_json::Value; +use std::collections::VecDeque; +use std::path::PathBuf; +use std::sync::Arc; + +/// An open control port. +pub struct Remote { + server: control::Server, + /// Calls in arrival order; the first one that edits holds the rest back during a drag. + waiting: VecDeque, + token: String, + /// `control.json`, when it could be written. + file: Option, +} + +/// Opens the control port; failures go to the status bar (the window still opens). +pub fn start(app: &mut App, ctx: &egui::Context, port: u16) { + let token = match control::token_from_env().map_or_else(control::new_token, Ok) { + Ok(t) => t, + Err(e) => { + app.status_err(tr!("Remote control is off: {reason}", reason = e)); + return; + } + }; + let wake_ctx = ctx.clone(); + let server = match control::listen(port, token.clone(), Arc::new(move || wake_ctx.request_repaint())) { + Ok(s) => s, + Err(e) => { + app.status_err(tr!("Remote control is off: port {port} is in use or not allowed ({reason}). Is another AniCraft already open with remote control?", port = port, reason = e)); + return; + } + }; + let file = control::control_file(); + let written = file.as_ref().map(|path| { + let contents = control::ControlFile { port: server.port, token: token.clone(), pid: std::process::id(), version: env!("CARGO_PKG_VERSION").to_string() }; + platform::write_private_file(path, contents.to_json().to_string().as_bytes()) + }); + if let Some(Err(e)) = &written { + // The port works with ANICRAFT_CONTROL_TOKEN; without the file a bridge can't find it. + app.status_err(tr!("Remote control is on, but its token could not be saved ({reason}); set ANICRAFT_CONTROL_TOKEN for the assistant.", reason = e)); + } + let file = if matches!(written, Some(Ok(()))) { file } else { None }; + app.remote = Some(Remote { server, waiting: VecDeque::new(), token, file }); +} + +/// The port, while remote control is on (the status bar shows it). +pub fn port(app: &App) -> Option { + app.remote.as_ref().map(|r| r.server.port) +} + +/// Whether the person is in the middle of an edit a remote one must not join. +fn person_is_dragging(app: &App, ctx: &egui::Context) -> bool { + app.drag != Drag::None || app.plugin_dialog.is_some() || (app.s.in_gesture() && ctx.egui_is_using_pointer()) +} + +/// Runs the waiting calls: at the start of a frame, so their edits draw in this one. +pub fn poll(app: &mut App, ctx: &egui::Context) { + let Some(r) = app.remote.as_mut() else { return }; + while let Some(req) = r.server.try_recv() { + r.waiting.push_back(req); + } + loop { + let dragging = person_is_dragging(app, ctx); + let Some(r) = app.remote.as_mut() else { return }; + let Some(next) = r.waiting.front() else { return }; + if next.changes_document() && dragging && !next.expired() { + // Look again shortly: the drag ends without a remote wake-up. + ctx.request_repaint_after(std::time::Duration::from_millis(50)); + return; + } + let Some(req) = r.waiting.pop_front() else { return }; + // (An expired call is refused without running: it leaves the person's gesture alone.) + if req.changes_document() && !req.expired() && !dragging && app.s.in_gesture() { + // A typed property change still open: it becomes its own undo step first. + app.s.end_gesture(); + } + req.run(&mut Live(app)); + } +} + +/// On exit: calls still waiting are told so, and `control.json` goes (if it is still ours). +pub fn finish(app: &mut App) { + let Some(mut r) = app.remote.take() else { return }; + for req in r.waiting.drain(..) { + // i18n-exempt: the protocol's English, read by the assistant (as MCP) + req.refuse("AniCraft is closing"); + } + if let Some(path) = &r.file { + let ours = std::fs::read_to_string(path).ok().and_then(|t| control::ControlFile::parse(&t).ok()).is_some_and(|c| c.token == r.token); + if ours { + let _ = std::fs::remove_file(path); + } + } +} + +/// The window as the tools' host: commands run with the follow-up the person's own get (the +/// status line, the view a new document resets, Open Recent). +struct Live<'a>(&'a mut App); + +impl mcp::Host for Live<'_> { + fn session(&self) -> &Session { + &self.0.s + } + fn execute(&mut self, id: &str, params: &Value) -> Result { + let selected = self.0.s.selection.len(); + let revision = self.0.s.revision; + let v = self.0.s.execute(id, params).map_err(|e| e.to_string())?; + // An edit to the document behind the start screen: show the document, so the person + // sees it land (ADR 0059's start screen otherwise covers the workspace). + if self.0.s.revision != revision { + self.0.start = None; + } + self.0.announce(id, &v, selected); + Ok(v) + } +} + +#[cfg(test)] +mod tests { + use crate::platform; + + /// The CLI finds `control.json` with its own copy of the settings-folder rule (it can't use + /// the shell); they must agree, or the bridge looks in the wrong place. + #[test] + fn the_bridge_looks_for_the_token_in_the_settings_folder() { + assert_eq!(anicraft_cli::control::settings_dir(), platform::config_dir()); + assert_eq!(anicraft_cli::control::control_file(), platform::config_dir().map(|d| d.join("control.json"))); + } +} From 5967b274b2953ad3050a930a407855e812bef7e9 Mon Sep 17 00:00:00 2001 From: lienatanael1-beep Date: Thu, 12 Nov 2026 15:32:09 +0700 Subject: [PATCH 2/2] docs: ADR 0070 is reserved for #216 Co-Authored-By: Claude Opus 5.5 --- docs/adr/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/README.md b/docs/adr/README.md index 65918325..4f01eaae 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -23,4 +23,4 @@ has to renumber because another PR merged first. | Number | Pull request | Topic | |---|---|---| | 0037 | #38 (outside contribution) | Interface languages | -| 0070 | feat/live-control | Live control port | +| 0070 | #216 | Live control port |