EffectCraft: An open-source motion graphics and compositing tool written by scratch in pure Rust
Merge main into #2279; keep main's Scripts subfolders (RESERVED_FOLDERS) next to the Startup/Shutdown constants, merge docs rows
bflatasticbd34ab21b62c
diff --cc apps/effectcraft-web/src/app.rsindex 314649421,60ff2f8d3..737f59f6a--- a/apps/effectcraft-web/src/app.rs+++ b/apps/effectcraft-web/src/app.rs@@@ -254,13 -272,12 +272,14 @@@ pub async fn start(canvas_id: String) -}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).- let restored = !empty && !query_flag("demo") && persist::restore(&mut session);- if !restored && !empty {+ // `?empty`: a blank project; `?demo`: the demo project; otherwise what the config's+ // `startup` says (default: the last visit's project, the demo on a first visit).+ let demo = query_flag("demo");+ let restored = !empty && !demo && startup.restores() && persist::restore(&mut session);+ if !restored && !empty && (demo || startup.demo_when_nothing_restored()) {let _ = session.execute("file.openDemoProject", json!({}));}api::set_info("restored", json!(restored));diff --cc crates/automation/src/confine.rsindex d2f4c70eb,67e5aef98..f7e05ef2e--- a/crates/automation/src/confine.rs+++ b/crates/automation/src/confine.rs@@@ -134,9 -167,18 +166,18 @@@ 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)")));}+ // Scripts can't grant themselves the access the user withheld+ // (`effectcraft_engine::prefs::Scripting::same_permissions`), and neither may a confined+ // agent: `prefs.set` saves the settings file, so a script run long after this session+ // would still have it. (`prefs.reset` only puts the defaults back, which grant nothing.)+ if id == "prefs.set" && prefs_keys(params).iter().any(|k| is_scripting_pref(k)) {+ return Err(Error::BadArgs(+ "`prefs.set`: the Scripting settings decide what a script may do, so they can't be changed while file access is confined".into(),+ ));+ }if id == "engine.batch" {for step in params.get("steps").and_then(Value::as_array).into_iter().flatten() {let Some(inner) = step.get("command").or_else(|| step.get("id")).and_then(Value::as_str) else { continue };diff --cc crates/engine/src/cmd/scripts.rsindex 3131bed60,f4162043d..16e5d222f--- a/crates/engine/src/cmd/scripts.rs+++ b/crates/engine/src/cmd/scripts.rs@@@ -5,10 -5,8 +5,11 @@@//! settings on the desktop, so dropping `.jsx` files in those folders works too. File ▸ Scripts//! 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.+ //! (`window.scriptPanel`), running with `this` = the panel as in After Effects. A subfolder of+ //! either folder (one level) is a submenu named after it; its scripts are named `Folder/File.jsx`.+//! * **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@@@ -25,18 -23,11 +26,23 @@@ use crate::{EngineError, Event, Result/// 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;+ /// [`PANELS_DIR`]'s name in [`SCRIPTS_DIR`]: it holds the panels, so it is not a folder of scripts.+ const PANELS_FOLDER: &str = "ScriptUI Panels";+ /// Subfolders of Scripts that hold scripts the app runs itself (panels; launch and quit, as in+ /// After Effects): never listed as File ▸ Scripts submenus.+ const RESERVED_FOLDERS: [&str; 3] = [PANELS_FOLDER, "Startup", "Shutdown"];/// 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 Effectsdiff --cc docs/plugins.mdindex a72eb1561,2117152a1..a388ce305--- a/docs/plugins.md+++ b/docs/plugins.md@@@ -12,11 -12,12 +12,12 @@@ Guide)| After Effects | EffectCraft | ||---|---|---|| Effect plug-ins (C/C++ SDK, `.aex` / `.plugin`) | [Effect plug-ins](#effect-plug-ins): WebAssembly modules (plug-in API v1) or Rust; the `Plug-ins` folder next to the settings loads at start-up | Different ABI: After Effects SDK plug-ins can't run (G8) |- | 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 |+ | 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; a subfolder (one level) is a submenu named after it | Same || File ▸ Scripts ▸ Run Script File… (`.jsx`, `.jsxbin`) | `.jsx` / `.js` | Gap: `.jsxbin` (an undocumented binary encoding) |+ | File ▸ Scripts ▸ Recent Script Files: the 10 most recently run scripts; Cmd+Option+Shift+D (Ctrl+Alt+Shift+D on Windows) reruns one | File ▸ Scripts ▸ Recent Script Files lists the 10 scripts run last (script files and File ▸ Scripts entries, newest first, kept in the settings); Cmd+Alt+Shift+D runs the most recent one again (`file.runScript {"recent": 0}`, a key that can be changed in Edit ▸ Keyboard Shortcuts) | Same || 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 |+ | `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 (a subfolder, one level, is a submenu named after it), 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 || `app.settings` (kept in the preferences between sessions) | Kept in `script_settings.json` in the settings folder (`script.settings.get` / `script.settings.save`) | Same |@@@ -38,12 -39,13 +39,17 @@@ journaled and the same as the UI's actifile.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.+ * A subfolder of `Scripts/` is a submenu of File ▸ Scripts named after the folder, and its scripts+ are named `Folder/File.jsx` in `file.scripts.list` and `file.runScript`. One level of folders is+ listed; deeper folders are not. `file.uninstallScript` removes only scripts at the top of the+ Scripts folders: delete a script in a subfolder yourself. A subfolder may be a link to another+ folder (an extension's own), and uninstall never deletes a file through it.## ScriptUI panelsdiff --cc docs/scripting-parity.mdindex 515713669,1d808726a..fed54f1c5--- a/docs/scripting-parity.md+++ b/docs/scripting-parity.md@@@ -21,9 -21,9 +21,9 @@@ our own scripts; no real-world script l| Scripting object model | `app`, `Project`, items, layers, properties, keys, eases, render queue, `TextDocument`, `Shape`, markers, `File`/`Folder`, `Socket`, `app.settings` | Same classes, edits run through undoable engine commands; match names table; layers, groups and properties are callable (`layer("Effects")(1)` is `.property(...)`) | good | `crates/script` tests (≈ 10 test files) || `$.evalFile`, `BridgeTalk` | Evaluate another script file; identify the host application and message other Adobe applications | `$.evalFile` evaluates a file relative to the calling file (nested at most 32 deep, under the scripts' file gate) and returns its last value; `BridgeTalk` names the host honestly (`appName` `effectcraft`, its version); messaging other applications throws "not supported" | partial | `tests_evalfile.rs` (#760); no inter-application messaging || 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 |+| `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 (a Startup script's tasks go on until EffectCraft quits); 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) |+ | Scripts menu, ScriptUI Panels folder | yes | yes; a subfolder (one level) of either folder is a submenu named after it | 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 | `crates/script/src/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 |diff --cc docs/target-app-parity.mdindex 831c5e2d4,34829d406..628b716d9--- a/docs/target-app-parity.md+++ b/docs/target-app-parity.md@@@ -117,10 -117,10 +117,10 @@@ compositing and effects dominate; audi| 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) |+ | Effects and animation presets | 14% | 85% | 40% | 70–130 | All 306 effects exist, but rendered output is unmeasured against After Effects; 76 built-in presets (text, Transitions, Backgrounds, Behaviors) 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) || 3D (Classic and Advanced) | 6% | 82% | 35% | 35–65 | No FBX/USD/STL models, no Substance materials, mesh displacement unverified; no 3D transform gizmos (#392, #347); reflections (#261); camera aperture (#260); #489 and #315 are closed || Tracking and AI-assisted tools | 5% | 80% | 35% | 35–70 | Object Matte (26.2) has the effect, the viewer tool (click / box), background tracking, Freeze and the 26.5 disk cache, not yet compared with After Effects; Roto Brush (MobileSAM) and face tracking (MediaPipe) unmeasured against After Effects; camera-tracker view (#505) || Preview and cache | 7% | 92% | 40% | 25–50 | Playback stutters on cached frames (#595, #304); late audio (#504, #335); #329 and #554 are closed; no benchmark against After Effects |