Skip to content

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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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<Va
report_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.rs
index 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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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.md
index 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 click
that 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.md
index 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 vie
on 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). ScriptUI
panels 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), keyboard
shortcuts 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 kept
diff --git a/docs/plugins.md b/docs/plugins.md
index 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 docs
file.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 settings
folder). 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}` runs
one; `file.uninstallScript {name}` removes an installed one.
diff --git a/docs/scripting-parity.md b/docs/scripting-parity.md
index 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 expression
performance benchmark 4–8 h.
diff --git a/docs/target-app-parity.md b/docs/target-app-parity.md
index 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) |