EffectCraft: An open-source motion graphics and compositing tool written by scratch in pure Rust
Scripts: the Startup and Shutdown folders run at launch and quit
dotCooCooefe7581f9395
diff --git a/apps/effectcraft-web/src/app.rs b/apps/effectcraft-web/src/app.rsindex 3f462bd2a..d5a767c03 100644--- a/apps/effectcraft-web/src/app.rs+++ b/apps/effectcraft-web/src/app.rs@@ -238,6 +238,8 @@ pub async fn start(canvas_id: String) -> Result<(), JsValue> {}let mut session = session();session.load_settings();+ // Scripts in Scripts/Startup run before a project opens.+ let _ = session.execute("file.runStartupScripts", json!({}));let recovery = session.begin_recovery();// `?empty`: a blank project; `?demo`: the demo project; otherwise the last visit's// project (the demo on a first visit).diff --git a/apps/effectcraft/src/main.rs b/apps/effectcraft/src/main.rsindex 2bc3265dd..99dc7ce1c 100644--- a/apps/effectcraft/src/main.rs+++ b/apps/effectcraft/src/main.rs@@ -243,6 +243,9 @@ fn main() -> eframe::Result {// Fit the window to its monitor, or put it back where it was (still hidden).let saved_window = session.config.as_deref().and_then(window::load);let opened = cc.winit_window().map(|w| window::restore(w, saved_window));+ // Scripts in Scripts/Startup run before a project opens (a failing one is reported in+ // a toast).+ let _ = session.execute("file.runStartupScripts", json!({}));let recovery = if control_port.is_none() { session.begin_recovery() } else { None };let project = files.iter().find(|f| is_project_file(f)).cloned();if let Some(p) = project {@@ -455,6 +458,8 @@ impl eframe::App for Desktop {self.launch.exited();self.window.save(self.app.session.config.as_deref());self.app.on_exit();+ // Scripts in Scripts/Shutdown run with the project closed.+ let _ = self.app.session.execute("file.runShutdownScripts", json!({}));}fn raw_input_hook(&mut self, ctx: &egui::Context, raw_input: &mut egui::RawInput) {diff --git a/crates/automation/src/confine.rs b/crates/automation/src/confine.rsindex f396b3da0..d2f4c70eb 100644--- a/crates/automation/src/confine.rs+++ b/crates/automation/src/confine.rs@@ -28,10 +28,9 @@ pub struct Confinement {write: Vec<PathBuf>,}-/// Commands that run code, act outside the project or open other applications.+/// Commands that run code, act outside the project or open other applications, besides the+/// commands that run scripts ([`effectcraft_engine::commands::scripts::RUNS_SCRIPTS`]).const REFUSED: &[&str] = &[- "script.run",- "file.runScript","file.installScript","file.installScriptUIPanel","file.uninstallScript",@@ -135,7 +134,7 @@ impl Confinement {/// Check engine command `id` with `params` before it runs. Returns what must still be looked/// up and passed to [`Confinement::check_lookup`] for commands that write implicitly.pub fn check_command(&self, id: &str, params: &Value) -> Result<Option<Lookup>> {- if REFUSED.contains(&id) {+ if REFUSED.contains(&id) || effectcraft_engine::commands::scripts::RUNS_SCRIPTS.contains(&id) {return Err(Error::BadArgs(format!("`{id}` is not available while file access is confined (--automation-read-root/--automation-write-root)")));}if id == "engine.batch" {diff --git a/crates/automation/src/tests.rs b/crates/automation/src/tests.rsindex 6e622b377..241eae720 100644--- a/crates/automation/src/tests.rs+++ b/crates/automation/src/tests.rs@@ -1376,6 +1376,18 @@ fn automation_roots_confine_file_access() {// Scripts can read and write anything: refused.denied(&mut s, "run_script", json!({"code": "1 + 1"}));denied(&mut s, "execute_command", json!({"command": "file.runScript", "params": {"path": p(&read, "x.jsx")}}));+ for (id, params) in [+ ("file.runStartupScripts", json!({})),+ ("file.runShutdownScripts", json!({})),+ // ScriptUI panels run their script when they open.+ ("window.scriptPanel", json!({"name": "Layer Tools.jsx"})),+ ("window.restoreScriptPanels", json!({})),+ ] {+ let msg = denied(&mut s, "execute_command", json!({"command": id, "params": params}));+ assert!(msg.contains("not available while file access is confined"), "{id}: {msg}");+ let msg = denied(&mut s, "batch", json!({"steps": [{"command": id, "params": params}]}));+ assert!(msg.contains("not available while file access is confined"), "{id}: {msg}");+ }// Writes to the files the agent named: none outside.assert_eq!(std::fs::read_dir(&outside).unwrap().count(), 1, "only the unconfined save");let _ = std::fs::remove_dir_all(&base);diff --git a/crates/engine/src/commands/batch.rs b/crates/engine/src/commands/batch.rsindex 4bfd2b2b1..aecb42a8d 100644--- a/crates/engine/src/commands/batch.rs+++ b/crates/engine/src/commands/batch.rs@@ -9,8 +9,9 @@ use serde_json::{Value, json};use super::{CommandSpec, always, bad, str_p};use crate::{EngineError, Result, Session};-/// Commands that can't run inside a batch (they replace the project or nest batches).-const NOT_IN_BATCH: &[&str] = &["engine.batch", "file.runScript", "script.run"];+/// Commands that can't run inside a batch (they nest batches), besides the commands that run+/// scripts ([`super::scripts::RUNS_SCRIPTS`]).+const NOT_IN_BATCH: &[&str] = &["engine.batch"];/// Resolve a `$N` / `$N.key.0.key` reference against the results so far.fn reference(s: &str, results: &[Value]) -> Option<Result<Value>> {@@ -64,7 +65,7 @@ fn batch(s: &mut Session, p: &Value) -> Result<Value> {.or_else(|| step.get("id")).and_then(Value::as_str).ok_or_else(|| bad("engine.batch", "each step needs `command` (a command id)"))?;- if NOT_IN_BATCH.contains(&id) {+ if NOT_IN_BATCH.contains(&id) || super::scripts::RUNS_SCRIPTS.contains(&id) {return Err(bad("engine.batch", format!("`{id}` can't run inside a batch")));}let params = substitute(step.get("params").unwrap_or(&json!({})), results)?;diff --git a/crates/engine/src/commands/file_more.rs b/crates/engine/src/commands/file_more.rsindex 74a86e1d8..f5314e64b 100644--- a/crates/engine/src/commands/file_more.rs+++ b/crates/engine/src/commands/file_more.rs@@ -480,7 +480,7 @@ fn run_script(s: &mut Session, p: &Value) -> Result<Value> {}_ => return Err(bad("file.runScript", format!("step {}: needs `command`", i + 1))),};- if id == "file.runScript" || id == "script.run" {+ if super::scripts::RUNS_SCRIPTS.contains(&id.as_str()) {return Err(bad("file.runScript", "scripts can't run scripts"));}let r = if from_file { s.execute_for_script(&id, params) } else { s.execute(&id, params) };@@ -505,7 +505,7 @@ fn is_jsxbin(name: &str) -> bool {}/// A script error becomes a toast and a command error.-fn report_js(s: &mut Session, name: &str, out: Value) -> Result<Value> {+pub(crate) fn report_js(s: &mut Session, name: &str, out: Value) -> Result<Value> {if let Some(e) = out.get("error").filter(|e| !e.is_null()) {let line = e.get("line").and_then(Value::as_u64).map(|l| format!(" (line {l})")).unwrap_or_default();let msg = e.get("message").and_then(Value::as_str).unwrap_or("script error");@@ -521,6 +521,13 @@ pub(crate) fn run_js_named(s: &mut Session, code: &str, name: &str) -> Result<Vareport_js(s, name, out)}+/// Run the code of the script file at `path` (its `#include`s and `$.fileName` use that path),+/// reported under its file name `name` (Startup and Shutdown scripts).+pub(crate) fn run_js_file(s: &mut Session, code: &str, path: &str, name: &str) -> Result<Value> {+ let out = run_js(s, code, path, false)?;+ report_js(s, name, out)+}+/// Run JavaScript through the session's scripting engine.fn run_js(s: &mut Session, code: &str, name: &str, console: bool) -> Result<Value> {let runner = s.script.ok_or_else(|| EngineError::Other("JavaScript scripting is not available in this build".into()))?;diff --git a/crates/engine/src/commands/scripts.rs b/crates/engine/src/commands/scripts.rsindex 24049459c..396c1c474 100644--- a/crates/engine/src/commands/scripts.rs+++ b/crates/engine/src/commands/scripts.rs@@ -6,6 +6,9 @@//! lists them with the bundled sample scripts and extensions ([`BUNDLED`]) and runs them by name; ScriptUI//! panels appear at the bottom of the Window menu and open as dockable panels//! (`window.scriptPanel`), running with `this` = the panel as in After Effects.+//! * **Startup and Shutdown scripts** in `Scripts/Startup/` and `Scripts/Shutdown/` run by+//! themselves, in alphabetical order: at launch (`file.runStartupScripts`) and as EffectCraft+//! quits, after the project is closed (`file.runShutdownScripts`).//! * **ScriptUI windows** (`scriptui.*`): list the open script windows, read their control//! trees, click buttons and set values like a user, close them (see [`crate::scriptui`]).//! * **Script settings** (`script.settings.*`): After Effects' `app.settings`, string values by@@ -22,6 +25,18 @@ use crate::{EngineError, Event, Result, Session, cmd, scriptui};/// The settings-store folders of installed scripts.pub const SCRIPTS_DIR: &str = "Scripts";pub const PANELS_DIR: &str = "Scripts/ScriptUI Panels";+/// The settings-store folders whose scripts run at launch and as EffectCraft quits.+pub const STARTUP_DIR: &str = "Scripts/Startup";+pub const SHUTDOWN_DIR: &str = "Scripts/Shutdown";+/// Commands that run script files or script code (a ScriptUI panel runs its script when it+/// opens). Scripts and batches can't run them, and confined automation sessions refuse them.+pub const RUNS_SCRIPTS: &[&str] =+ &["script.run", "file.runScript", "file.runStartupScripts", "file.runShutdownScripts", "window.scriptPanel", "window.restoreScriptPanels"];+/// Largest script file the Startup and Shutdown folders run (bytes), as `#include` and+/// `$.evalFile` allow.+const MAX_SCRIPT_BYTES: usize = 16 << 20;+/// Modal dialogs a Shutdown script may open one after another; each closes as if canceled.+const MAX_SHUTDOWN_DIALOGS: usize = 64;/// The ScriptUI panels open when EffectCraft last quit (settings store), reopened at launch.pub const OPEN_PANELS_FILE: &str = "scriptui_panels.json";/// Scripts' `app.settings` in the settings store: `{section: {key: value}}`, as After Effects@@ -308,6 +323,72 @@ fn restore_panels(s: &mut Session, _: &Value) -> Result<Value> {Ok(json!({"opened": opened, "failed": failed}))}+/// Run the scripts in `dir` of the settings store one after another, in alphabetical order (case+/// ignored), as After Effects runs its Startup and Shutdown folders. A script that fails is+/// reported in a toast and the log and listed in `failed`; the next one still runs. A script waiting in a+/// modal dialog is listed in `waiting` and goes on when the dialog closes; the next one runs+/// meanwhile. With `quitting`, no window is left to show a dialog in, so each dialog closes as+/// if canceled (`show()` returns 2) and the script runs on.+fn run_folder(s: &mut Session, dir: &str, quitting: bool) -> Value {+ let mut names: Vec<String> = s.config.as_ref().map(|c| c.list(dir)).unwrap_or_default().into_iter().filter(|n| is_script(n) && is_script_name(n)).collect();+ names.sort_by(|a, b| a.to_lowercase().cmp(&b.to_lowercase()).then_with(|| a.cmp(b)));+ let (mut ran, mut waiting, mut failed) = (vec![], vec![], vec![]);+ for name in names {+ let code = match s.config.as_ref().map(|c| c.read_bounded(&format!("{dir}/{name}"), MAX_SCRIPT_BYTES)) {+ Some(Ok(Some(code))) => code,+ read => {+ let why = match read {+ Some(Err(e)) => format!(": {e}"),+ _ => String::new(),+ };+ let error = format!("{name}: cannot read the script{why}");+ log::warn!("{dir}: {error}");+ s.events.push(Event::Toast { message: error.clone(), error: true });+ failed.push(json!({"name": name, "error": error}));+ continue;+ }+ };+ let is_waiting = |r: &Result<Value>| r.as_ref().is_ok_and(|v| v.get("waiting").and_then(Value::as_bool) == Some(true));+ // In a settings folder on disk, the script runs as its file, so `#include`, `$.fileName`+ // and `$.evalFile` find the files beside it.+ let path = s.config.as_ref().and_then(|c| c.dir()).map(|d| d.join(dir).join(&name).to_string_lossy().into_owned()).unwrap_or_else(|| name.clone());+ // Windows open before this script runs belong to other scripts, perhaps of the same name.+ let before: Vec<u32> = s.script_ui.windows.iter().map(|w| w.id).collect();+ let mut r = super::file_more::run_js_file(s, &code, &path, &name);+ let mut closed = 0;+ while quitting && closed < MAX_SHUTDOWN_DIALOGS && is_waiting(&r) {+ let Some(id) = s.script_ui.windows.iter().rev().find(|w| w.modal && w.script == path && !before.contains(&w.id)).map(|w| w.id) else { break };+ // report_js reports an error the script throws after its dialog closes, as it does for an+ // error in the script's first run.+ r = scriptui::close(s, &json!({"window": id})).and_then(|out| super::file_more::report_js(s, &name, out));+ closed += 1;+ }+ match r {+ Ok(_) if is_waiting(&r) => waiting.push(name),+ Ok(_) => ran.push(name),+ Err(e) => {+ // Also in the log: no frame draws a Shutdown script's toast.+ log::warn!("{dir}: {e}");+ failed.push(json!({"name": name, "error": e.to_string()}));+ }+ }+ }+ json!({"ran": ran, "waiting": waiting, "failed": failed})+}++/// `file.runStartupScripts`: run the scripts in `Scripts/Startup` (frontends call it once at+/// launch, before a project opens).+fn run_startup(s: &mut Session, _: &Value) -> Result<Value> {+ Ok(run_folder(s, STARTUP_DIR, false))+}++/// `file.runShutdownScripts`: close the project, then run the scripts in `Scripts/Shutdown`+/// (frontends call it as the app quits, after the unsaved-changes prompt).+fn run_shutdown(s: &mut Session, _: &Value) -> Result<Value> {+ s.replace_project(effectcraft_project::Project::default(), None);+ Ok(run_folder(s, SHUTDOWN_DIR, true))+}+/// Window ▸ <ScriptUI panel>: run the panel script (or bring its panel forward).fn open_panel(s: &mut Session, p: &Value) -> Result<Value> {let c = "window.scriptPanel";@@ -374,6 +455,24 @@ pub fn specs() -> Vec<CommandSpec> {always,restore_panels),+ cmd!(+ "file.runStartupScripts",+ "Run Startup Scripts",+ [],+ None,+ "{} → runs the scripts in Scripts/Startup in alphabetical order (frontends call it at launch) → {ran: [name], waiting: [name] (in a modal dialog), failed: [{name, error}]}",+ always,+ run_startup+ ),+ cmd!(+ "file.runShutdownScripts",+ "Run Shutdown Scripts",+ [],+ None,+ "{} → closes the project, then runs the scripts in Scripts/Shutdown in alphabetical order (frontends call it as the app quits; their modal dialogs close as if canceled) → {ran: [name], waiting: [name], failed: [{name, error}]}",+ always,+ run_shutdown+ ),crate::query!("script.settings.get", "Get Script Setting", "{section, key} → {have, value} (app.settings.haveSetting / getSetting)", settings_get),cmd!("script.settings.save",diff --git a/crates/script/src/lib.rs b/crates/script/src/lib.rsindex 5c1f8cdbb..8472881d9 100644--- a/crates/script/src/lib.rs+++ b/crates/script/src/lib.rs@@ -97,6 +97,8 @@ mod tests_include;#[cfg(test)]mod tests_panels;#[cfg(test)]+mod tests_startup;+#[cfg(test)]mod tests_tasks;#[cfg(test)]mod tests_ui;diff --git a/crates/script/src/runtime.rs b/crates/script/src/runtime.rsindex 192da5740..22e5279c8 100644--- a/crates/script/src/runtime.rs+++ b/crates/script/src/runtime.rs@@ -126,7 +126,7 @@ pub(crate) fn js_str(s: &str) -> JsValue {fn native_exec(_: &JsValue, args: &[JsValue], ctx: &mut Context) -> JsResult<JsValue> {let id = arg_string(args, 0, ctx)?;let mut params = arg_json(args, 1, ctx)?;- if id == "script.run" || id == "file.runScript" {+ if effectcraft_engine::commands::scripts::RUNS_SCRIPTS.contains(&id.as_str()) {return Err(throw("scripts can't run scripts"));}let keys = params.as_object_mut().and_then(|o| o.remove("__keys"));diff --git a/crates/script/src/tests_startup.rs b/crates/script/src/tests_startup.rsnew file mode 100644index 000000000..6c13aaf30--- /dev/null+++ b/crates/script/src/tests_startup.rs@@ -0,0 +1,269 @@+//! Startup and Shutdown scripts, as in After Effects: the scripts in the user's `Scripts/Startup`+//! and `Scripts/Shutdown` folders (in the settings folder) run in alphabetical order at launch and+//! as the app quits, after the project is closed.++use std::sync::Arc;++use effectcraft_engine::Session;+use effectcraft_engine::commands::scripts::{OPEN_PANELS_FILE, PANELS_DIR, SCRIPTS_DIR, SHUTDOWN_DIR, STARTUP_DIR};+use effectcraft_engine::config::{ConfigStore, MemoryConfig};+use effectcraft_engine::scriptui::WindowKind;+use serde_json::json;++fn session(store: &Arc<MemoryConfig>) -> Session {+ let mut s = Session::default();+ crate::install(&mut s);+ s.config = Some(store.clone());+ s+}++/// A script that appends `mark` to the `Startup Test` / `order` script setting.+fn mark(mark: &str) -> String {+ format!(+ r#"var k = app.settings.haveSetting("Startup Test", "order") ? app.settings.getSetting("Startup Test", "order") : "";+app.settings.saveSetting("Startup Test", "order", k + "{mark}");"#+ )+}++fn setting(s: &mut Session, key: &str) -> serde_json::Value {+ s.execute("script.settings.get", json!({"section": "Startup Test", "key": key})).unwrap()["value"].clone()+}++#[test]+fn startup_scripts_run_in_alphabetical_order_and_a_failing_one_does_not_stop_the_rest() {+ let store = Arc::new(MemoryConfig::default());+ store.write(&format!("{STARTUP_DIR}/b.jsx"), &mark("b")).unwrap();+ store.write(&format!("{STARTUP_DIR}/A.jsx"), &mark("A")).unwrap();+ store.write(&format!("{STARTUP_DIR}/B2.jsx"), &mark("B")).unwrap();+ store.write(&format!("{STARTUP_DIR}/C.js"), "throw new Error('no');").unwrap();+ store.write(&format!("{STARTUP_DIR}/d.jsx"), &mark("d")).unwrap();+ // Not scripts, or not in the Startup folder: not run.+ store.write(&format!("{STARTUP_DIR}/notes.txt"), &mark("x")).unwrap();+ store.write(&format!("{SCRIPTS_DIR}/Menu Script.jsx"), &mark("m")).unwrap();+ store.write(&format!("{SHUTDOWN_DIR}/Quit.jsx"), &mark("q")).unwrap();+ let mut s = session(&store);+ let r = s.execute("file.runStartupScripts", json!({})).unwrap();+ assert_eq!(r["ran"], json!(["A.jsx", "b.jsx", "B2.jsx", "d.jsx"]), "{r}");+ let failed: Vec<&str> = r["failed"].as_array().unwrap().iter().map(|f| f["name"].as_str().unwrap()).collect();+ assert_eq!(failed, ["C.js"]);+ assert_eq!(setting(&mut s, "order"), "AbBd");+ // The failing script is reported in a toast.+ let events = s.drain_events();+ assert!(events.iter().any(|e| matches!(e, effectcraft_engine::Event::Toast { message, error: true } if message.starts_with("C.js"))), "{events:?}");+ // The Startup folder's scripts are not offered in File ▸ Scripts.+ let list = s.execute("file.scripts.list", json!({})).unwrap();+ assert!(list.as_array().unwrap().iter().all(|e| e["name"] != "b.jsx"), "{list}");+}++#[test]+fn shutdown_scripts_run_after_the_project_is_closed() {+ let store = Arc::new(MemoryConfig::default());+ let probe = r#"app.settings.saveSetting("Startup Test", "items", String(app.project.numItems));"#;+ store.write(&format!("{SHUTDOWN_DIR}/Save State.jsx"), probe).unwrap();+ let mut s = session(&store);+ s.execute("script.run", json!({"code": r#"app.project.items.addComp("Main", 64, 64, 1, 1, 24);"#})).unwrap();+ assert!(!s.project.items.is_empty());+ let r = s.execute("file.runShutdownScripts", json!({})).unwrap();+ assert_eq!(r, json!({"ran": ["Save State.jsx"], "waiting": [], "failed": []}));+ assert_eq!(setting(&mut s, "items"), "0");+ assert!(s.project.items.is_empty());+}++#[test]+fn a_startup_dialog_stays_open_and_its_script_goes_on_when_it_closes() {+ let store = Arc::new(MemoryConfig::default());+ store.write(&format!("{STARTUP_DIR}/A Dialog.jsx"), &format!("new Window('dialog', 'Welcome').show();\n{}", mark("A"))).unwrap();+ store.write(&format!("{STARTUP_DIR}/B.jsx"), &mark("B")).unwrap();+ let mut s = session(&store);+ let r = s.execute("file.runStartupScripts", json!({})).unwrap();+ assert_eq!(r, json!({"ran": ["B.jsx"], "waiting": ["A Dialog.jsx"], "failed": []}));+ assert_eq!(setting(&mut s, "order"), "B");+ assert!(s.script_ui.windows.iter().any(|w| w.modal && w.title == "Welcome"));+ s.execute("scriptui.close", json!({})).unwrap();+ assert_eq!(setting(&mut s, "order"), "BA");+}++#[test]+fn shutdown_dialogs_close_as_if_canceled() {+ let store = Arc::new(MemoryConfig::default());+ let code = r#"var a = new Window("dialog", "One").show();+var b = new Window("dialog", "Two").show();+app.settings.saveSetting("Startup Test", "shown", a + "," + b);"#;+ store.write(&format!("{SHUTDOWN_DIR}/Ask.jsx"), code).unwrap();+ // An error after the dialog closes is a failure.+ store.write(&format!("{SHUTDOWN_DIR}/Broken.jsx"), "new Window('dialog', 'Three').show();\nthrow new Error('late');").unwrap();+ let mut s = session(&store);+ let r = s.execute("file.runShutdownScripts", json!({})).unwrap();+ assert_eq!((&r["ran"], &r["waiting"]), (&json!(["Ask.jsx"]), &json!([])), "{r}");+ assert_eq!(r["failed"][0]["name"], "Broken.jsx", "{r}");+ assert!(r["failed"][0]["error"].as_str().is_some_and(|e| e.contains("late")), "{r}");+ assert_eq!(setting(&mut s, "shown"), "2,2");+ assert!(s.script_ui.windows.is_empty());+}++#[test]+fn shutdown_closes_only_its_own_scripts_dialogs() {+ let store = Arc::new(MemoryConfig::default());+ store.write(&format!("{STARTUP_DIR}/Same.jsx"), &format!("new Window('dialog', 'Startup').show();\n{}", mark("S"))).unwrap();+ store.write(&format!("{SHUTDOWN_DIR}/Same.jsx"), &format!("new Window('dialog', 'Shutdown').show();\n{}", mark("Q"))).unwrap();+ let mut s = session(&store);+ assert_eq!(s.execute("file.runStartupScripts", json!({})).unwrap()["waiting"], json!(["Same.jsx"]));+ let r = s.execute("file.runShutdownScripts", json!({})).unwrap();+ assert_eq!(r, json!({"ran": ["Same.jsx"], "waiting": [], "failed": []}));+ // The Startup script's dialog is still open, and its script has not gone on.+ assert_eq!(setting(&mut s, "order"), "Q");+ let titles: Vec<&str> = s.script_ui.windows.iter().map(|w| w.title.as_str()).collect();+ assert_eq!(titles, ["Startup"]);+}++#[test]+fn oversized_scripts_are_not_run() {+ let store = Arc::new(MemoryConfig::default());+ let big = format!("{}\n{}", "//".repeat(8 << 20), mark("x"));+ store.write(&format!("{STARTUP_DIR}/Big.jsx"), &big).unwrap();+ let mut s = session(&store);+ let r = s.execute("file.runStartupScripts", json!({})).unwrap();+ assert_eq!(r["ran"], json!([]));+ assert_eq!(r["failed"][0]["name"], "Big.jsx");+ let events = s.drain_events();+ assert!(events.iter().any(|e| matches!(e, effectcraft_engine::Event::Toast { message, error: true } if message.starts_with("Big.jsx"))), "{events:?}");+ assert_eq!(setting(&mut s, "order"), "");+}++#[test]+fn scripts_in_a_settings_folder_on_disk_include_files_beside_them() {+ use effectcraft_engine::config::DirConfig;+ let root = std::env::temp_dir().join(format!("ec-startup-include-{}", std::process::id()));+ let _ = std::fs::remove_dir_all(&root);+ for (file, code) in [+ (format!("{STARTUP_DIR}/lib/helper.jsx"), mark("i")),+ (format!("{STARTUP_DIR}/Main.jsx"), format!("#include \"lib/helper.jsx\"\n{}", mark("m"))),+ (format!("{SHUTDOWN_DIR}/Ask.jsx"), format!("new Window('dialog', 'Bye').show();\n{}", mark("q"))),+ ] {+ let path = root.join(file);+ std::fs::create_dir_all(path.parent().unwrap()).unwrap();+ std::fs::write(path, code).unwrap();+ }+ let mut s = Session::default();+ crate::install(&mut s);+ s.config = Some(Arc::new(DirConfig::new(&root)));+ let r = s.execute("file.runStartupScripts", json!({})).unwrap();+ assert_eq!(r, json!({"ran": ["Main.jsx"], "waiting": [], "failed": []}));+ assert_eq!(setting(&mut s, "order"), "im");+ // A Shutdown script run as its file still has its dialog closed.+ let r = s.execute("file.runShutdownScripts", json!({})).unwrap();+ assert_eq!(r, json!({"ran": ["Ask.jsx"], "waiting": [], "failed": []}));+ assert_eq!(setting(&mut s, "order"), "imq");+ let _ = std::fs::remove_dir_all(&root);+}++/// A session with one comp, for checking that a refused command leaves the project open.+fn session_with_comp(store: &Arc<MemoryConfig>) -> Session {+ let mut s = session(store);+ s.execute("script.run", json!({"code": r#"app.project.items.addComp("Main", 64, 64, 1, 1, 24);"#})).unwrap();+ assert!(!s.project.items.is_empty());+ s+}++const FOLDER_COMMANDS: [&str; 2] = ["file.runStartupScripts", "file.runShutdownScripts"];++#[test]+fn scripts_cannot_run_the_startup_or_shutdown_folders() {+ let store = Arc::new(MemoryConfig::default());+ for id in FOLDER_COMMANDS {+ let mut s = session_with_comp(&store);+ let r = s.execute("script.run", json!({"code": format!("app.run('{id}', {{}})")})).unwrap();+ assert!(r["error"]["message"].as_str().is_some_and(|m| m.contains("scripts can't run scripts")), "{id}: {r}");+ assert!(!s.project.items.is_empty(), "{id}");+ }+}++#[test]+fn command_scripts_cannot_run_the_startup_or_shutdown_folders() {+ let store = Arc::new(MemoryConfig::default());+ for id in FOLDER_COMMANDS {+ let mut s = session_with_comp(&store);+ let e = s.execute("file.runScript", json!({"steps": [{"command": id}]})).unwrap_err().to_string();+ assert!(e.contains("scripts can't run scripts"), "{id}: {e}");+ assert!(!s.project.items.is_empty(), "{id}");+ }+}++#[test]+fn batches_cannot_run_the_startup_or_shutdown_folders() {+ let store = Arc::new(MemoryConfig::default());+ for id in FOLDER_COMMANDS {+ let mut s = session_with_comp(&store);+ let e = s.execute("engine.batch", json!({"steps": [{"command": id}]})).unwrap_err().to_string();+ assert!(e.contains("can't run inside a batch"), "{id}: {e}");+ assert!(!s.project.items.is_empty(), "{id}");+ }+}++/// A ScriptUI panel whose script appends `p` to the `Startup Test` / `order` setting each time it+/// runs, remembered as open at the last quit.+fn session_with_panel(store: &Arc<MemoryConfig>) -> Session {+ store.write(&format!("{PANELS_DIR}/Mark Panel.jsx"), &format!("this.add('statictext', undefined, 'Mark');\n{}", mark("p"))).unwrap();+ store.write(OPEN_PANELS_FILE, &json!({"open": ["Mark Panel.jsx"]}).to_string()).unwrap();+ session(store)+}++fn panel_open(s: &Session) -> bool {+ s.script_ui.windows.iter().any(|w| w.kind == WindowKind::Panel && w.script == "Mark Panel.jsx")+}++/// The commands that open ScriptUI panels, which run the panel's script.+fn panel_commands() -> [(&'static str, serde_json::Value); 2] {+ [("window.scriptPanel", json!({"name": "Mark Panel.jsx"})), ("window.restoreScriptPanels", json!({}))]+}++#[test]+fn scripts_cannot_open_script_panels() {+ for (id, params) in panel_commands() {+ let store = Arc::new(MemoryConfig::default());+ let mut s = session_with_panel(&store);+ // Opened by the user: a script's call would only bring it forward.+ s.execute("window.scriptPanel", json!({"name": "Mark Panel.jsx"})).unwrap();+ let r = s.execute("script.run", json!({"code": format!("app.run('{id}', {params})")})).unwrap();+ assert!(r["error"]["message"].as_str().is_some_and(|m| m.contains("scripts can't run scripts")), "{id}: {r}");+ assert_eq!(setting(&mut s, "order"), "p", "{id}");+ assert_eq!(store.read(OPEN_PANELS_FILE).unwrap_or_default(), json!({"open": ["Mark Panel.jsx"]}).to_string(), "{id}");+ }+}++#[test]+fn command_scripts_and_batches_cannot_open_script_panels() {+ for (id, params) in panel_commands() {+ let store = Arc::new(MemoryConfig::default());+ let mut s = session_with_panel(&store);+ let e = s.execute("file.runScript", json!({"steps": [{"command": id, "params": params}]})).unwrap_err().to_string();+ assert!(e.contains("scripts can't run scripts"), "{id}: {e}");+ let e = s.execute("engine.batch", json!({"steps": [{"command": id, "params": params}]})).unwrap_err().to_string();+ assert!(e.contains("can't run inside a batch"), "{id}: {e}");+ assert!(!panel_open(&s), "{id}");+ assert_eq!(setting(&mut s, "order"), "", "{id}");+ }+}++#[test]+fn the_app_still_reopens_script_panels_at_launch() {+ let store = Arc::new(MemoryConfig::default());+ let mut s = session_with_panel(&store);+ // As the desktop and web apps call it at launch.+ let r = s.execute("window.restoreScriptPanels", json!({})).unwrap();+ assert_eq!(r, json!({"opened": ["Mark Panel.jsx"], "failed": []}));+ assert!(panel_open(&s));+ assert_eq!(setting(&mut s, "order"), "p");+}++#[test]+fn empty_or_missing_folders_run_nothing() {+ let none = json!({"ran": [], "waiting": [], "failed": []});+ let store = Arc::new(MemoryConfig::default());+ let mut s = session(&store);+ assert_eq!(s.execute("file.runStartupScripts", json!({})).unwrap(), none);+ // A session without a settings folder.+ let mut s = Session::default();+ crate::install(&mut s);+ assert_eq!(s.execute("file.runShutdownScripts", json!({})).unwrap(), none);+}diff --git a/docs/agents.md b/docs/agents.mdindex 5c58d24b7..42b88b066 100644--- a/docs/agents.md+++ b/docs/agents.md@@ -580,7 +580,9 @@ A dialog's `show()` waits for the user: the `script.run` / `file.runScript` repl`"waiting": true`, and the script continues (its final output arrives in the reply of the clickthat closes the dialog). File ▸ Scripts: `file.scripts.list`, `file.runScript {"name": …}`,`file.installScript` / `file.installScriptUIPanel {"path": …}`, `window.scriptPanel {"name": …}`,-`window.restoreScriptPanels` (the panels open when the app last quit). Scripts' `app.settings`:+`window.restoreScriptPanels` (the panels open when the app last quit), `file.runStartupScripts` and+`file.runShutdownScripts` (the scripts in `Scripts/Startup` and `Scripts/Shutdown`; the second closes+the project first). Scripts' `app.settings`:`script.settings.get {"section": …, "key": …}` and `script.settings.save {…, "value": …}`.Extension points and the bundled extensions: [plugins.md](plugins.md).diff --git a/docs/gaps.md b/docs/gaps.mdindex f8fcd64c2..a956ed953 100644--- a/docs/gaps.md+++ b/docs/gaps.md@@ -299,7 +299,10 @@ Issues #41–#47 (all from the Linux AppImage 0.1.1, 5 October): panning the vieon the same extension points as After Effects: scripts, ScriptUI panels and effect plug-ins([plugins.md](plugins.md#extension-points-compared-with-after-effects) compares them). ScriptUIpanels in the user's ScriptUI Panels folder are listed in the Window menu, dock like any panel- and open again at the next launch. Missing: the Startup and Shutdown script folders, keyboard+ and open again at the next launch. The scripts in the Startup folder run at launch, and the desktop+ app runs the Shutdown folder's scripts as it quits. Missing: a global scope that scripts share+ for the session (a Startup script's variables and functions are not available to later+ scripts), keyboardshortcuts for scripts and `.jsxbin`; `#include` / `#target` directives landed (#759,[scripting-parity.md](scripting-parity.md)).- Done so far: ease presets (#254) cover what ease-curve plug-ins are used for: easing curves keptdiff --git a/docs/plugins.md b/docs/plugins.mdindex a688a89b0..a72eb1561 100644--- a/docs/plugins.md+++ b/docs/plugins.md@@ -15,7 +15,7 @@ Guide):| Scripts folder: its scripts are listed in File ▸ Scripts | `Scripts/` in the settings folder (File ▸ Scripts ▸ Install Script File… copies a script there), listed in File ▸ Scripts with the bundled samples | Same || File ▸ Scripts ▸ Run Script File… (`.jsx`, `.jsxbin`) | `.jsx` / `.js` | Gap: `.jsxbin` (an undocumented binary encoding) || ExtendScript preprocessor directives (`#include`, `#target`, `#targetengine`) | `#include` / `//@include` / `#includepath` inline files relative to the script (once each, depth-limited, file gate applies); `#target`, `#targetengine`, `#strict` are ignored | Same |-| `Scripts/Startup` and `Scripts/Shutdown`: run in alphabetical order when the app starts and quits | Not run | Gap |+| `Scripts/Startup` and `Scripts/Shutdown`: run in alphabetical order when the app starts and quits | `Scripts/Startup/` and `Scripts/Shutdown/` in the settings folder, in alphabetical order (case ignored): the Startup scripts run at launch before a project opens, and the Shutdown scripts run as the desktop app quits, after the project is closed. A Startup script that fails is reported in a toast and in the log, a Shutdown script that fails is reported in the log, and the next script still runs | Partial: each script runs in its own global scope, so variables and functions a Startup script defines are not available to later scripts; a Startup script's modal dialog stays open while the next scripts run and the app starts; a Shutdown script's modal dialogs close as if canceled; the web app runs no Shutdown scripts || `Scripts/ScriptUI Panels`: listed at the bottom of the Window menu, dockable like the app's own panels, `this` is the panel | `Scripts/ScriptUI Panels/` in the settings folder (File ▸ Scripts ▸ Install ScriptUI Panel… copies one there), listed at the bottom of the Window menu, docked like any panel, `this` is the panel; the panels open when the app quits open again at the next launch | Same. Where a panel was docked isn't kept: workspace layouts aren't saved between launches || Keyboard shortcuts for scripts (the Keyboard Shortcuts editor lists the scripts of the Scripts folder) | Shortcuts bind to commands and menu entries; the File ▸ Scripts and Window menu entries of scripts aren't offered | Gap || Running a script from the command line (`afterfx -r script.jsx`) | `effectcraft-cli script`, the control channel's and MCP's `script.run` | Same purpose, other entry points |@@ -38,6 +38,10 @@ journaled and the same as the UI's action. The `effectcraft-script` crate's docsfile.jsx`, or `script.run {code, name}` over the control channel and MCP.* Install one: File ▸ Scripts ▸ Install Script File… (or copy it into `Scripts/` in the settingsfolder). It is listed in File ▸ Scripts at once (After Effects asks for a restart).+* Run one at every launch or quit: copy it into `Scripts/Startup/` or `Scripts/Shutdown/` in the+ settings folder. These scripts are not listed in File ▸ Scripts. `file.runStartupScripts` and+ `file.runShutdownScripts` run them and return `{ran, waiting, failed}`; the desktop app calls them at+ launch and quit, and the web app calls `file.runStartupScripts` at launch.* `file.scripts.list` lists installed and bundled scripts and panels; `file.runScript {name}` runsone; `file.uninstallScript {name}` removes an installed one.diff --git a/docs/scripting-parity.md b/docs/scripting-parity.mdindex 7ef7e9080..55bd4a212 100644--- a/docs/scripting-parity.md+++ b/docs/scripting-parity.md@@ -23,7 +23,7 @@ our own scripts; no real-world script library has been run against both apps.| ScriptUI | Dialogs, palettes, dockable panels, resource strings, `onDraw` / ScriptUIGraphics, mouse events | Same, dockable panels reopen at launch | good | `ui_scriptui`, `tests_ui*` || `app.scheduleTask` / `cancelTask` | One-shot and repeating tasks (polling, panel refresh) until `cancelTask` | Same: repeating tasks run every `delay` ms (at least 50 ms, at most 64 pending per script) until `cancelTask`, until they throw (reported once, then cancelled), or until their owner goes: a script's last window closing, or the project closing for scripts without windows; frontends tick them every frame, agents with `script.runTasks` | good | `tests_tasks.rs` (#773); one-shot tasks of a script file still run right after it, not after their delay || Scripts menu, ScriptUI Panels folder | yes | yes | same | [plugins.md](plugins.md) |-| Startup / Shutdown folders | yes | not run | missing | plugins.md |+| Startup / Shutdown folders | yes | `Scripts/Startup` runs at launch and `Scripts/Shutdown` runs as the desktop app quits, after the project is closed, each in alphabetical order | partial | `tests_startup.rs`; each script has its own global scope, so a Startup script's variables and functions are not available to later scripts ([plugins.md](plugins.md)) || `#include`, `#target` directives | yes | `#include` / `//@include` / `#includepath` inline files relative to the including script (once each, nested at most 32 deep, under the scripts' file gate; errors name the included file and line); `#target`, `#targetengine`, `#strict` are ignored | good | `tests_include.rs` (#759); installed scripts and panels have no folder of their own, so they include from the project's folder or absolute paths || `.jsxbin` | yes | no | out of scope | No public specification || Keyboard shortcuts for scripts | yes | no | missing | plugins.md |@@ -34,7 +34,7 @@ our own scripts; no real-world script library has been run against both apps.## Estimate-**≈ 20–40 h**: `#include` / `#target` (landed, #759) and Startup / Shutdown folders 4–8 h as first estimated (Startup / Shutdown remain), script shortcuts 2–4 h,+**≈ 20–40 h**: `#include` / `#target` (landed, #759) and Startup / Shutdown folders 4–8 h as first estimated (Startup / Shutdown landed; a global scope shared between scripts remains), script shortcuts 2–4 h,a corpus of public scripts and expressions with the fixes it finds 10–20 h, an expressionperformance benchmark 4–8 h.diff --git a/docs/target-app-parity.md b/docs/target-app-parity.mdindex ff7cc3ef9..831c5e2d4 100644--- a/docs/target-app-parity.md+++ b/docs/target-app-parity.md@@ -117,7 +117,7 @@ compositing and effects dominate; audio is light). Hours are to full parity for| Project, footage and import | 8% | 92% | 55% | 25–45 | No relative paths or relinking when a project moves; Media Browser lists AVI, which it can't import (TGA/HDR/DPX/MXF import since #745, #756, #767); #431, #324, #552 and #351 are closed || Compositions, layers and compositing | 13% | 98% | 60% | 30–55 | 32-bpc blend modes differed from After Effects (#494, closed); expand precomps in place (#601); #527, #510, #513, #539 and #540 are closed || Animation: keyframes, graph editor, motion paths, puppet | 15% | 97% | 55% | 35–60 | Only scalar ease is measured against After Effects (168 samples); puppet lag (#586); #456, #457, #355, #553 and #318 are closed; Proportional Scrubbing (26.2) |-| Expressions and scripting | 7% | 93% | 65% | 20–40 | `.jsxbin`, Startup/Shutdown folders, script shortcuts (`#include` landed, #759); external editor (#364); see [scripting-parity.md](scripting-parity.md) |+| Expressions and scripting | 7% | 93% | 65% | 20–40 | `.jsxbin`, a global scope shared between scripts, script shortcuts (`#include` landed, #759; Startup/Shutdown folders run); external editor (#364); see [scripting-parity.md](scripting-parity.md) || Shapes, masks and roto | 9% | 93% | 45% | 30–50 | Open mask and shape issues (#1004, #999, #1042, #932); #510, #513, #527, #509 and #303 are closed; paste SVG/AI as shape layers (26.3; SVG markup pastes since #738) || Text and typography | 7% | 94% | 50% | 20–35 | CJK text in comps renders wrongly (#453); paragraph alignment inverted (#316); soft text at Fit (#417, mostly fixed by #444); toolbar font options (#550); #483 and #583 are closed; variable-font filter landed (#741) || Effects and animation presets | 14% | 85% | 40% | 70–130 | All 306 effects exist, but rendered output is unmeasured against After Effects; 54 built-in presets (text, Transitions, Backgrounds) against After Effects' 621 ([effects-parity.md](effects-parity.md)); open effect bugs (#580 crash, #463, #369, #473, #474; #514 and #526 are closed); effect colour labels (26.5); see [effects-parity.md](effects-parity.md) |