M14.4: scripting with an After Effects-style JavaScript object model

New crate effectcraft-script (L4): boa runtime with app/Project/CompItem/
Layer/PropertyGroup/Property/TextDocument/MarkerValue/RenderQueue/File
object model over engine commands (undoable, undo groups), AE match-name
table, file/network security gate. Entry points: script.run command,
File > Scripts > Run Script File (.jsx/.js), Window > Script Console,
effectcraft-cli script, MCP run_script. Engine: project.delete/duplicate,
prop.renameGroup/setGroupEnabled/removeGroup/duplicateGroup/moveGroup.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/agents.md

@@ -49,6 +49,7 @@ The server speaks JSON-RPC 2.0 over stdio, one message per line, and supports MC
 |---|---|
 | `list_commands {filter?, enabled_only?}` | Discover command ids, their param docs, and whether each can run now. |
 | `execute_command {command, params?}` | Run any command (undoable). |
+| `run_script {code, name?}` | Run JavaScript with the After Effects-style scripting object model (`app.project`, `comp.layers.addText(…)`, `layer.property("ADBE Transform Group").property("ADBE Position").setValueAtTime(…)`…). Returns `{ok, result, output, error: {message, line, column}}`; edits are undoable. |
 | `get_project` / `get_comp {comp?}` | Project items, comp settings and layers. |
 | `get_layer {layer, comp?, time?, flat?}` | A layer's property tree. Every node has a `path`. |
 | `get_property {layer, path, comp?, time?}` | Value at a time, keyframes and expression. |
@@ -191,6 +192,19 @@ effectcraft-cli exec file.exportLottie '{"comp":"Main","path":"main.json","inclu
 effectcraft-cli exec file.importLottie '{"path":"anim.json"}' main.ecproj --save
 ```
 
+Scripts written against After Effects' documented scripting API run with `script`:
+
+```sh
+effectcraft-cli script build.jsx --save-as main.ecproj     # empty project unless one is given
+effectcraft-cli script --eval 'app.project.item(1).numLayers' main.ecproj --json
+effectcraft-cli script tweak.jsx --bridge 9877              # against the live app
+```
+
+`writeLn`/`$.writeln`/`alert` output is printed, then the value of the last expression. A script
+error exits with status 1 and `file:line:col: message`. Scripts may read files only in the
+project's folder and may not write files or use the network unless the user turns on Preferences ▸
+Scripting & Expressions ▸ Allow Scripts to Write Files and Access Network.
+
 `file.exportLottie` returns `{path, bytes, warnings}`: the warnings list every feature Lottie
 cannot express (most effects, cameras and lights, layer styles, audio, video footage…), so an
 agent can check what a player will not show. A `.lottie` path writes a dotLottie archive.

docs/architecture.md

@@ -30,13 +30,15 @@ cpal or muda. Everything in L0 to L4, the egui UI and the web app also build for
 | L3 | `gpu` | The GPU compositor and GPU effects on wgpu compute shaders (Metal, Vulkan, Direct3D 12, WebGPU), checked against the CPU renderer |
 | L3 | `lottie` | Lottie JSON / dotLottie import and export (layers, precomps, eased and spatial keyframes, shapes, masks, mattes) with a warnings list for what Lottie cannot express |
 | L4 | `engine` | `Session`: project, undo history, editor state, the command registry and menus |
-| L4 | `host` | A fully wired `Session` (media, expressions, exporter) for the frontends |
+| L4 | `script` | Scripting: JavaScript (boa) with an After Effects-style object model (`app.project`, comps, layers, properties, render queue) whose edits run engine commands; AE match names |
+| L4 | `host` | A fully wired `Session` (media, expressions, scripting, exporter) for the frontends |
 | L5 | `ui-egui` | The desktop interface: docking, panels, viewer, timeline, graph editor, dialogs, control channel |
 | L5 | `automation` | The MCP server, headless or bridged to the running app |
 | L6 | apps `effectcraft`, `effectcraft-cli`, `effectcraft-web` | Desktop app; command-line tool (render, exec, get/set, MCP); the browser app (wasm32, [web.md](web.md)) |
 
 Allowed same-layer edges: `path → keyframe, raster`, `text → path`, `effects → project, text, path, track`,
-`media / expr / export / gpu → render`, `export → media`, `lottie → format`, `host → engine`.
+`media / expr / export / gpu → render`, `export → media`, `lottie → format`, `host → engine, script`,
+`script → engine`.
 
 ## 2. Time
 
@@ -182,6 +184,28 @@ Expressions are JavaScript, run by boa, with After Effects' object model (`thisC
 `time`, `value`, `wiggle`, `loopOut`, vector maths on arrays, and so on). A syntax error keeps the
 text, disables the expression and shows a warning, like After Effects.
 
+## 5a. Scripting
+
+`effectcraft-script` runs JavaScript (boa, a fresh context per run; the Script Console keeps one)
+with an object model written from the behaviour the After Effects Scripting Guide documents:
+`app`, `Project`, `ItemCollection`, `CompItem`/`FootageItem`/`FolderItem`, `LayerCollection`,
+`AVLayer`/`TextLayer`/`ShapeLayer`/`CameraLayer`/`LightLayer`, `PropertyGroup`/`Property`
+(values, keyframes, eases, expressions), `TextDocument`, `Shape`, `KeyframeEase`, `MarkerValue`,
+`RenderQueue`/`RenderQueueItem`/`OutputModule`, `File`/`Folder` and the enums. The model lives in
+`prelude.js`; it reads the session through `__query` (JSON snapshots of items, layers, property
+nodes, values and keys) and edits only through `__exec`, which runs engine commands, so every
+scripted edit is undoable and identical to the UI's. While a script runs the session is moved
+into a thread-local the natives borrow (nothing borrowed enters the JS heap); the comp a call
+targets is made active for that command only. `app.beginUndoGroup`/`endUndoGroup` fold the undo
+steps in between into one named step. Match names (`ADBE Transform Group`, `ADBE Position`,
+`ADBE Gaussian Blur 2`, `ADBE Vector Shape - Rect`…) come from a table in `matchnames.rs`; effect
+parameters are `<effect match name>-0001…`. `File` reads are limited to the project's folder, and
+writes and the network are refused, unless Preferences ▸ Scripting & Expressions ▸ Allow Scripts
+to Write Files and Access Network is on. Entry points: the `script.run` command
+(`Session::script`, set by the host), File ▸ Scripts ▸ Run Script File… (`.jsx`/`.js`; `.json`
+command scripts still run as steps), Window ▸ Script Console, `effectcraft-cli script` and the
+MCP `run_script` tool.
+
 ## 6. Commands, the UI seam and automation
 
 Every action is a command: an id, a label, a menu path, a shortcut, a parameter description,

docs/parity.md

@@ -75,7 +75,7 @@ library groundwork for mask tracking and Warp Stabilizer.
 
 What is left is concentrated in large systems: Roto Brush and Refine Edge, the 3D camera tracker,
 Advanced 3D (models, PBR, image-based lighting), the Warp Stabilizer and mask-tracking UI on top of
-the new tracking library, a JavaScript scripting object model, SVG/PSD import, WebM, a disk cache,
+the new tracking library, SVG/PSD import, WebM, a disk cache,
 the missing effect categories (3D Channel, Immersive Video, OCIO), native macOS menus, and
 wasm threads.
 
@@ -87,7 +87,7 @@ wasm threads.
 | Output | 85% | 4.2 | multiple output modules, pre-render, WebM, audio-only |
 | Audio | 85% | 0.5 | audio to keyframes |
 | Import | 78% | 4.5 | PSD, SVG as shapes, Lottie |
-| Automation | 76% | 3.3 | a JavaScript scripting object model |
+| Automation | ≈ 90% | 0.8 | scripting covers the documented core object model (AUT-2, M14.4: `app`, project items, comps, layers, properties and keyframes, text documents, markers, render queue, Script Console, `effectcraft-cli script`, MCP `run_script`); still missing: ScriptUI panels/dialogs, `.jsxbin`, sockets |
 | Shapes | 68% | 3.9 | taper and wave strokes (pen tool for shape paths and vertex editing landed in M6.5) |
 | Compositions | 67% | 7.4 | marker dialog, flowchart, Essential Graphics |
 | Animation | 65% | 10.4 | puppet, Wiggler/Smoother/Motion Sketch (motion-path handles and the graph editor transform box landed in M5.8) |