playrig 0.0.0-stage → 0.1.0

package/AGENTS.md

@@ -0,0 +1,106 @@
+# Playrig: guide for coding agents
+
+Playrig lets you control After Effects and Premiere Pro. You write a job script, submit it with the `playrig` CLI (alias `prg`), read the result, look at the frames, and iterate. This file is the canonical guide for any agent (Claude Code, Codex, others).
+
+| Edition | App | Job language | Job global |
+|---|---|---|---|
+| Playrig for After Effects (`ae`) | After Effects | ExtendScript (ES3), `.jsx` | `PLAYRIG` (`BRIDGE` is an alias) |
+| Playrig for Premiere Pro (`pr`) | Premiere Pro 25.6+ | modern JS in an async function body (`await` works), `.js` | `PLAYRIG` (`BRIDGE` is an alias), plus `ppro` (the `premierepro` module), `alert`, `confirm` |
+
+Only the editions the user installed work. Check which app is open and that its panel is started before submitting anything (with no panel answering, a job ends with "No result ... Is the app open with the Playrig panel started?").
+
+## Submit a job
+
+```
+playrig ae run job.jsx --snap "MAIN@4.5,9" --inspect "04_UI:2" --timeout 120
+playrig pr run job.js  --snap "My Sequence@4.5,9" --timeout 120
+playrig ae snap "MAIN@4.5,9"          # frames only, no job script
+playrig pr inspect "My Sequence"      # structure only
+playrig status <id> [--app ae|pr]
+playrig tail [--app ae|pr] [--all | --project <name>]
+playrig ae lib init|list|show|run|check|index|new ...   # your own recipe library (--lib <folder>)
+playrig ae scratch start | status | clean --yes    # same for `pr`
+playrig update [ae|pr|cli] [--check]               # newer versions; exit code 10 = update available
+playrig where [ae|pr|library|skills|inbox:ae|inbox:pr]
+```
+
+- Exit code is non-zero unless the job status is `ok`. `--json` prints the raw `result.json`.
+- Jobs travel through a folder: `<root>/inbox/<id>.jsx|.js` (+ `<id>.json` options) in, `<root>/out/<id>/result.json` out. Root: `--root`, else `$PLAYRIG_ROOT/<ae|pr>`, else `~/Documents/Playrig/<ae|pr>` (an existing `~/Documents/AE Bridge` or `Premiere Bridge` is used until the new folder exists).
+- The old `aeb` command still works (it prints a deprecation notice and forwards). Old job scripts that use `BRIDGE.` still run. The CLI and the installed panel must be updated together: a new CLI against an old panel fails with "PLAYRIG is undefined".
+
+## Read results and snapshots
+
+`playrig` prints status, `action`, `about`, `project:`, the error (message, line, source line), the log, the absolute path of each snapshot PNG, and the path to `result.json`. **Open the PNGs with your image reader and look at them.** Snapshots are taken after the job ends, from the final state.
+
+- **Always check the `project:` line** before acting on a log, and print the open project path at the start of work (`app.project.file` in AE, `PLAYRIG.project.path` in Premiere). The open project has not always been the expected one.
+- `project log:` shows the project log folder. If it says NOT SYNCED, tell the user (usually the project is unsaved).
+- Before starting on a project, read `<project folder>/EDIT_LOGS/JOURNAL.md`, `assets.ae.md` (AE) or `assets.md` (Premiere), and `NOTES.md` if present (decisions written by hand).
+- **Never save the user's project** from a job and never overwrite the project file. Edits are in memory until they save; say so in your report.
+
+## Declare an action and describe every job
+
+Every job has one action. Put it in the first lines of the job, then a one-line description:
+
+```js
+// @action animate.keyframes
+// Moved the chip pops 0.2 s later to follow the new timing
+```
+(or `--action <id> --desc "..."`). The description appears in the panel. Undeclared jobs are inferred and shown as "(inferred)".
+
+- AE actions (`packages/ae/lib/actions.json`): `bridge.test`, `project.inspect`, `frame.export`, `footage.import`, `comp.create`, `precomp.create`, `layer.add`, `layer.edit`, `text.edit`, `shape.edit`, `effect.add`, `animate.keyframes`, `expression.set`, `render.queue`, `recipe.run`, `recipe.<id>`, `scratch.baseline`, `scratch.cleanup`, `job.rejected`, `custom`.
+- Premiere actions (`packages/pr/plugin/actions.js`): `bridge.test`, `project.inspect`, `frame.export`, `media.import`, `sequence.clone`, `sequence.rename`, `sequence.delete`, `clip.place`, `clip.edit`, `score.place`, `score.sync`, `audio.level`, `audio.effect`, `organize.project`, `organize.archive`, `organize.structure`, `scratch.baseline`, `scratch.cleanup`, `job.rejected`, `custom`.
+- When a genuinely new kind of job appears, add an entry to the list instead of leaving it `custom`.
+
+## Inside a job
+
+Each job is one undo group labelled `Playrig: <id>` (AE: automatic; Premiere: one `PLAYRIG.transact(...)` per undo step). One Edit > Undo reverts it.
+
+- AE: `PLAYRIG.log(msg)`, `.comp(name)`, `.snap(comp, time)`, `.contactSheet(comp, start, end, step)`, `.inspect(comp, depth, time)`, `.ret(value)`, `.root`, `.json.stringify/parse`. Parameters passed with `--param k=v` arrive as `var P`.
+- Premiere: `PLAYRIG.project`, `.sequence(name)`, `.transact(name, ca => ...)`, `.sync / .adopt / .owned / .clips / .place / .remove / .tag / .untag`, `.setLevelDb`, `.levelKeys`, `.dbToLevel`, organizer calls (`.organizeProject`, `.importInto`, `.ensureBin`, `.moveItem`, ...). Full list: `packages/pr/README.md`.
+- `alert()` is redirected to the log; `confirm()` returns false. Don't rely on dialogs.
+- A job cannot be interrupted once started; keep loops bounded. Jobs share one engine, so wrap code in a function and don't leak globals.
+- If a job errors halfway, its partial changes stay.
+
+## Rules for jobs
+
+### After Effects (each one came from a real bug)
+
+1. **Shape group order: the first group draws on top.** A background rectangle added before content hides it. After adding each group, move it to the top with `group.moveTo(1)`, or add groups front to back.
+2. **Keyframes on layers that don't start at 0.** Opacity keys set by script on a precomp layer with `startTime ≠ 0` ended up offset by that start time. Avoid keyframing offset layers from scripts: animate inside the precomp, or set keys then check `keyTime()` against what you intended.
+3. **ExtendScript is ES3.** No `let`/`const`, arrow functions, template literals, `Array.prototype.map/forEach/indexOf`, `JSON`, `Math.sign` or `String.trim`. (`PLAYRIG.json.stringify/parse` exist.)
+4. **Property references go stale.** After `addProperty()` on a group, earlier references to siblings can become invalid. Re-fetch by index or matchName after each add.
+5. **Use matchNames, not display names**, wherever one exists (`"ADBE Vector Shape - Rect"`, `"ADBE Text Animator"`, ...). Display names break in non-English After Effects.
+6. **Expression Selector amount should return `[v, v, v]`**, not a scalar.
+7. **Always finish a job with a snapshot** of the frames you changed and look at them before reporting success. Status `ok` doesn't mean the picture is right.
+8. Fonts must be installed. After Effects substitutes missing fonts silently: check `textInfo.font` in `inspect` output.
+9. Change what exists, don't rebuild: update existing comps in place; `lib run --replace` replaces only that recipe's own layers (tagged `aeb:<recipe>:<instance>` in the layer comment; that tag name is kept for compatibility). Experiment in `SCRATCH-*` comps and clean up with `scratch`.
+
+### Premiere Pro (each one cost a debugging round)
+
+1. **Create actions inside `PLAYRIG.transact(name, ca => ...)`**, not before it (otherwise "The script object is no longer valid"). One `transact` = one undo step.
+2. **Keyframe times are SOURCE time.** A key at timeline `t` on a clip with in-point `i` and start `s` goes at `t + (i - s)`. Premiere doesn't validate it. `levelKeys` handles it.
+3. **Volume > Level: 0 dB = 0.1778** (`dbToLevel(db)`). Channel Volume 0.178 = unity. Read a known 0 dB clip before judging a mix.
+4. **`createSetInPointAction` trims the head** (clip start moves, out point stays). To slip the source under a fixed position: set in point, set out point, then `createMoveAction` back.
+5. **`createSetOutPointAction` extends or trims the tail.** To extend a clip by 2 s add 2 to its out point (the source must have the media).
+6. **`createOverwriteItemAction` snaps to frames** (2.6 s becomes 2.58 s at 24 fps) and overwrites whatever is there; a longer clip overwritten by a shorter one leaves a remnant. Check `getTrackItems` afterwards or remove the old clip first (what `sync` does).
+7. **Removing clips:** build the selection inside `TrackItemSelection.createEmptySelection(sel => ...)` and add the remove action in that callback. `createRemoveItemsAction` has failed in practice; prefer `sync`. Project items: `parentBin.createRemoveItemAction(item)`; sequences: `project.deleteSequence(seq)`.
+8. **Importing:** `PLAYRIG.importInto(paths, binPath)` (creates the bin). Never leave imports loose at the root. Look items up recursively. Bins are created, renamed and moved from the PARENT.
+9. **Effects:** `ppro.AudioFilterFactory.createComponentByDisplayName("Studio Reverb", clip)` then `chain.createAppendComponentAction(comp)`. Values are normalised 0 to 1; read them back. Don't assume effect or param names from another language or version: list `getDisplayNames()` / `displayName` first.
+10. **Snapshots** are written at the sequence's own size. An empty timeline gives black frames, which is correct. Always snapshot after a picture change.
+11. **Audio cannot be auditioned from here.** Verify by reading back clip times, levels and keyframes and by measuring files with ffmpeg; say plainly that nothing was listened to.
+12. **Change what you own.** Clips Playrig places are tagged with a name suffix `[pb:<family>:<key>]` (kept for compatibility). `await PLAYRIG.sync(seq, "sfx", desired)` moves, swaps, adds or removes only tagged clips; running it twice changes nothing; pass `{ dryRun: true }` to preview. Bring hand-placed clips under management once with `adopt`. Don't delete a sequence or empty a track for a small change.
+13. **Keep the project organized.** The bin scheme is data (`<project>/EDIT_LOGS/organize.json`, else the personal default, else `packages/pr/organize.default.json`). Dry-run `organizeProject({ dryRun: true })` before reorganizing a project that has drifted. Archive, never delete.
+14. Scratch experiments (cloning a sequence, test imports): `playrig pr scratch start` first, `scratch clean --yes` after.
+
+## Skills (optional, Claude Code)
+
+`playrig install skills` copies the skills into `./.claude/skills` (`--global` for `~/.claude/skills`):
+- `create-video`: brief to export across both apps (start here for a video task).
+- `create-ae-video`, `use-ae-recipes`, `create-ae-recipe`: build After Effects scenes from your own recipe library, and add recipes to it (from a description or a reference video).
+- `score-video`: music and sound effects in Premiere, via Epidemic Sound.
+
+**Recipes are yours.** Playrig ships the tooling and an empty starter library, not recipes. Run `playrig ae lib init` once to create `~/Documents/Playrig/library` (or point `--lib <folder>` / `$PLAYRIG_LIBRARY` at one), then grow it with `create-ae-recipe` or `playrig ae lib new <category>/<id>`, and run `playrig ae lib index`. `playrig where library` prints the folder in use; read its `INDEX.md` first, open one recipe, run it with `playrig ae lib run <id> --param k=v`.
+
+## Security
+
+Anything that can write to the inbox can run code in the app. Keep the inbox private. A panel does nothing until the user presses Start.

package/LICENSE

@@ -0,0 +1,37 @@
+Playrig License, version 1.0
+
+Copyright (c) 2026 Vivek Nigam. All rights reserved.
+
+"Playrig" (the "Software") means the software distributed with this notice, including the After Effects panel, the Premiere Pro panel, the command-line tool, the agent skills and their documentation, under whatever name it is released (the name may change). "Licensor" means Vivek Nigam. "You" means the person or organisation using the Software.
+
+This is a source-available license. It is NOT an open-source license: you may read and use the Software, but you may not redistribute it.
+
+1. WHAT YOU MAY DO
+   You may, free of charge, install and run the Software, as obtained from the Licensor's official channels (the official npm package, the official releases page, or an Adobe distribution the Licensor has published), for your own work, including paid client or commercial video work, on computers you or your organisation own or control. You may keep the Software's copyright and license notices in place and share links to the official channels and to the official installation instructions.
+
+2. WHAT YOU MAY NOT DO
+   a. Distribute. You may not copy, publish, upload, host, resell, sublicense, rent, lend or otherwise make the Software, or any part of it, available to anyone else, whether modified or not, whether for money or free. This includes bundling it into another product, template, installer or course download, and mirroring it. Point people to the official channels instead.
+   b. Remove notices. You may not remove or change copyright, license or attribution notices.
+   c. Misrepresent. You may not present the Software, or a modified version, as your own work or as endorsed by the Licensor, and you get no right to use the name "Playrig" or any other name, logo or trademark of the Licensor.
+   d. Circumvent protections. You may not bypass or disable the signature and checksum checks that the Software uses to install updates, or use the update mechanism to deliver anything other than official releases.
+
+3. MODIFICATIONS MUST BE CONTRIBUTED BACK
+   You may modify the Software for your own use only on this condition: you must contribute every modification back to the Licensor, in a form the Licensor can use (a patch, a pull request or the changed files), through the contribution channel the Licensor publishes (currently the issue tracker at https://github.com/viveknigam3003/playrig-releases/issues, or any other channel stated on the official releases page), within 30 days of first using the modification. By contributing, you grant the Licensor a perpetual, worldwide, irrevocable, royalty-free, transferable license to use, modify, publish and distribute your contribution as part of the Software, under this license or any other, and you confirm that you have the right to do so. You keep no right to distribute your modification yourself (section 2a still applies). If you do not contribute a modification within that time, your license under section 1 ends for the modified version, and you must stop using that version.
+
+4. THIRD-PARTY MATERIAL
+   The Software includes icons from Tabler Icons (MIT License), which stay under their own license. The Software works with Adobe After Effects and Adobe Premiere Pro, which you must license separately from Adobe. The Licensor is not affiliated with Adobe. Adobe, After Effects and Premiere Pro are trademarks of Adobe Inc.
+
+5. OWNERSHIP
+   The Licensor keeps all rights not expressly granted. Nothing here transfers ownership of the Software to you. Your own projects, footage and the video you make with the Software belong to you.
+
+6. TERMINATION
+   Your license ends automatically if you breach this license. It also ends for versions the Licensor withdraws for security or legal reasons, if the Licensor gives notice through the official channels. On termination you must stop using the Software and delete your copies.
+
+7. NO WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. THE SOFTWARE CONTROLS OTHER APPLICATIONS AND CAN CHANGE PROJECTS AND FILES: KEEP BACKUPS OF YOUR WORK. THE SOFTWARE RUNS CODE INSIDE YOUR APPLICATIONS: KEEP ITS JOB FOLDER PRIVATE.
+
+8. LIMITATION OF LIABILITY
+   TO THE MAXIMUM EXTENT ALLOWED BY LAW, THE LICENSOR IS NOT LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL OR CONSEQUENTIAL DAMAGES, OR FOR LOSS OF DATA, PROJECTS, PROFITS OR BUSINESS, ARISING FROM THE SOFTWARE OR ITS USE, EVEN IF ADVISED OF THE POSSIBILITY. THE LICENSOR'S TOTAL LIABILITY FOR ANY CLAIM IS LIMITED TO THE AMOUNT YOU PAID FOR THE SOFTWARE, WHICH MAY BE ZERO.
+
+9. CHANGES TO THIS LICENSE
+   The Licensor may release new versions of the Software under a different license. Versions you already received stay under the license they came with.

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# Playrig
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Playrig lets Claude, Codex or any coding agent control After Effects and Premiere Pro, so you can "vibe edit" your videos while keeping the control and sophistication these apps give you out of the box.
+
+It is one product with two editions: **Playrig for After Effects** and **Playrig for Premiere Pro**. Install one, or both.
+
+## Install
+
+Requires Node 18 or newer.
+
+```bash
+npm install -g playrig      # the CLI: `playrig`, short alias `prg`
+
+playrig install ae          # Playrig for After Effects: panel into After Effects' ScriptUI Panels folder
+playrig install pr          # Playrig for Premiere Pro: builds "Playrig (PR).ccx" and opens the Creative Cloud installer
+playrig install skills      # optional: agent skills (video workflow, recipes, scoring) into ./.claude/skills (--global for ~/.claude/skills)
+playrig install all         # whatever applies of the above
+```
+
+- **After Effects**: copies `Playrig.jsx` and `Playrig lib/` into every `Adobe After Effects*/Scripts/ScriptUI Panels` folder it finds. If the folder needs admin rights, the command prints the exact `sudo cp` line. Restart After Effects, then open the panel from the Window menu. An old `AE Bridge.jsx` panel must be deleted by hand.
+- **Premiere Pro**: needs Premiere Pro 25.6 or newer. If the installer refuses the package (it is unsigned), load `plugin/manifest.json` through the Adobe UXP Developer Tool instead. Then open the panel from Window > Extensions.
+- **Updates**: the After Effects panel updates itself from **Settings > About > Check for Updates** (and checks once a day, installing only when you agree unless you turn on automatic install). The Premiere Pro panel checks too and links to the new package; Creative Cloud delivers updates for marketplace installs. `playrig update` does the same from a terminal.
+- Use `--dry-run` to see what would happen. `playrig where` shows where everything is.
+
+## Allow the apps to let Playrig work
+
+- **After Effects**: Preferences > Scripting & Expressions > turn on **Allow Scripts to Write Files and Access Network**. Do this once.
+- **Premiere Pro**: there is no such preference; it does not apply. The panel is a UXP plugin that declares file access in its manifest, and Premiere asks you to consent when you install it and the first time Playrig opens a file or folder. Say yes.
+
+## 30-second quickstart
+
+**After Effects**
+
+1. Open a project, open **Window > Playrig**, press the power icon (**Start**).
+2. In a terminal: `playrig ae run "$(playrig where ae)/examples/hello.jsx"`
+3. Ask your agent: "Read AGENTS.md, then add a title comp and show me frame 2." Frames come back as PNGs the agent looks at.
+
+**Premiere Pro**
+
+1. Open a project, open **Window > Extensions > Playrig**, press **Start**.
+2. In a terminal: `playrig pr run "$(playrig where pr)/examples/hello.js"`
+3. Ask your agent: "Read AGENTS.md, then list my sequences and export a frame at 4 seconds."
+
+## CLI reference
+
+```
+playrig <ae|pr> run <job> [--id <id>] [--action <id>] [--desc "..."] [--snap "<comp or sequence>@t1,t2"]...
+                            [--inspect "<comp>:<depth>" | "<sequence>"] [--timeout 120] [--no-undo] [--json] [--root <dir>]
+playrig <ae|pr> snap "<comp or sequence>@t1,t2,..."    export frames, no job script
+playrig <ae|pr> inspect "<comp>:<depth>" | "<sequence>"
+playrig status <id> [--app ae|pr]                      app is found for you when the id is unique
+playrig tail [--app ae|pr] [--all | --project <name>] [--limit 10]
+playrig <ae|pr> scratch start | status | clean --yes   remove only what was added since start
+playrig ae lib init|list|show|run|index|check|new ...  your own recipe library (none is shipped; `lib init` creates a starter)
+playrig install <ae|pr|skills|all> [--dry-run] [--no-open] [--to <folder>] [--global]
+playrig update [ae|pr|cli] [--check]                   check for newer versions (exit code 10 = update available) and install
+playrig where [ae|pr|library|skills|inbox:ae|inbox:pr]
+```
+
+`prg` is the same command. `playrig run <file.jsx|.js>` picks the app from the extension. Job files are `.jsx` (ExtendScript) for After Effects and `.js` for Premiere Pro. Exit code is non-zero unless the job status is `ok`.
+
+Inbox folder: `--root`, else `$PLAYRIG_ROOT/<ae|pr>`, else `~/Documents/Playrig/<ae|pr>`. An existing `~/Documents/AE Bridge` or `~/Documents/Premiere Bridge` keeps being used until the new folder exists.
+
+Coming from the old names? `aeb ...` still works and prints a one-line deprecation notice, `BRIDGE.` in job scripts still works, and old panel settings are read on first start. Update the CLI and the panel together.
+
+Agents: read [AGENTS.md](AGENTS.md).
+
+## Security
+
+Anything that can write to the inbox folder can run code inside the app, with the app's access to your files. Keep the inbox in a private folder that only you can write to, and never share it or sync it to a folder others can write to. A panel does nothing until you press **Start**; stop it when you are not using it. The panels' only network use is the daily update check (switch it off in Settings > About). Updates for After Effects are installed only after a SHA-256 and signature check against a key shipped with the panel.
+
+## License
+
+Free to use; not free to redistribute. Modifications must be contributed back. See [LICENSE](LICENSE).
+
+## Repository
+
+One repo, two independently versioned editions: `packages/cli` (npm `playrig`), `packages/ae`, `packages/pr`. Tag releases per edition: `ae-v1.2.0`, `pr-v0.3.0`, `cli-v0.1.0`.

package/bin/playrig.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict';
+// playrig and its short alias prg both run this file.
+require('../lib/main.js').run(process.argv.slice(2));

package/editions/ae/README.md

@@ -0,0 +1,144 @@
+# Playrig for After Effects
+
+A folder-based link between Claude and a live After Effects project (AE 2026, macOS and Windows).
+Claude writes an ExtendScript job into a watched folder; a dockable panel runs it in your open project and writes back a log, errors, project inspection and PNG frames. You only render the final output.
+
+## Security: read this first
+
+**Anything that can write to `<root>/inbox` can run arbitrary code inside After Effects**, with access to your files. Use a private folder that only you (and the tools you trust) can write to. Don't put the root in a shared or synced-to-others location.
+
+- The panel runs only `*.jsx` files from `<root>/inbox` whose name matches `^[A-Za-z0-9_-]{1,64}$` and which are under 2 MB. Anything else is marked `rejected` and not run.
+- The only network use is the update check (see Updates below): once a day it asks GitHub for `updates/versions.json`, and downloads only when you choose to install. Turn it off in Settings > About. Jobs themselves never use the network.
+- It is off until you press **Start**, and off again after every After Effects restart unless you tick **Start automatically**.
+- Each job is one undo step. Optionally, a backup copy of the project file is made before each job.
+
+## Prerequisites
+
+- After Effects → Preferences → Scripting & Expressions → **Allow Scripts to Write Files and Access Network**: ON.
+- Fonts used by jobs must be installed. After Effects substitutes missing fonts silently; `inspect` reports the font in use (`textInfo.font`).
+- Node 18+ for the `playrig` CLI.
+
+## Install
+
+`playrig install ae` does this for you (it prints a `sudo` line if the folder needs admin rights). By hand: copy into After Effects' `Scripts/ScriptUI Panels` folder (macOS `/Applications/Adobe After Effects <version>/Scripts/ScriptUI Panels/`, Windows `C:\Program Files\Adobe\Adobe After Effects <version>\Support Files\Scripts\ScriptUI Panels\`):
+
+1. `panel/Playrig.jsx` into that folder.
+2. The contents of `lib/` (`bridge-api.jsxinc`, `panel-core.jsxinc`, `actions.json`, `icons/png/`; `dev.jsxinc` is dev only) into a new folder `Playrig lib/` next to it.
+3. Restart After Effects and open **Window > Playrig** (the menu entry is the panel's file name).
+4. Press the **power icon** to start, or open the **gear** and tick **Start automatically**. The folder (default `~/Documents/Playrig/ae`; an existing `~/Documents/AE Bridge` is used until the new one exists) is set in Settings > General.
+
+Upgrading from "AE Bridge": delete `AE Bridge.jsx` and `AE Bridge lib/`; saved settings are picked up automatically.
+
+## Updates
+
+`Playrig.jsx` in ScriptUI Panels is a small, stable stub. The real panel lives in `Playrig lib/` beside it, and a newer verified copy in your user data folder (`~/Library/Application Support/Playrig/ae/current`, or `%APPDATA%\Playrig\ae\current`) is preferred when there is one. So updates install without admin rights; restart After Effects to use them.
+
+- **Settings > About > Check for Updates**: reads the feed, shows what's new, and offers **Install update**. A banner also appears in the panel when one is found.
+- **Check for updates automatically** (on by default): once a day. **Install updates automatically** is off by default.
+- An update is installed only if its URL is on the Playrig GitHub releases page, its SHA-256 matches the feed, and its signature verifies against `update-key.pem` shipped with the panel. Signature checks use `openssl` (macOS has it; stock Windows doesn't). Without it the panel only reports the update: run `playrig update ae`, which verifies natively.
+- The previous version is kept in `.../ae/previous`. To go back, delete `current` and rename `previous` to `current`.
+
+## The panel
+
+```
+Playrig for After Effects                                ● Idle   ⏻   ⚙
+Motion_Videos_AI                (open project)
+
+Recent jobs                                     35 jobs
+Status        Action                    Time
+✓ ok          Add layers                02-10-26 17:42
+✗ error       Create comp               02-10-26 16:50
+(summary of the selected job)                 [Details...]
+```
+
+- **Power icon**: grey = stopped, green = running. **Gear**: Playrig for After Effects Settings (General: bridge folder, Start automatically, Back up the project file before each job; About).
+- **Recent jobs is per project**: it shows the jobs of the project that is open (read from `EDIT_LOGS/results/` beside the `.aep`) and switches when you open another project, even while the bridge is stopped. Latest 50, newest first. For an unsaved project only this session's jobs show ("Save the project to keep its job history with it").
+- Select a row to see a one-line summary of what the job did under the list (ScriptUI has no per-row tooltips); **double-click** a row or press **Details...** for the job details window (what happened, action, id, start + duration, project, error, log, frames, returned value, result path). A `*` after an action means it was inferred from the script rather than declared.
+- Status uses an icon plus the word: ok (green), error (red), rejected (orange), timeout (amber), unknown (grey).
+- Dev only: the details window also shows the job script when `lib/dev.jsxinc` is present (see `DEV_ONLY.md`).
+
+The panel creates `inbox/ running/ done/ out/<id>/ backups/ rejected/` under the root.
+
+## Use
+
+```
+playrig ae run examples/hello.jsx
+playrig ae run examples/snap.jsx --snap "Comp 1@0,1"
+playrig ae run my-job.jsx --inspect "04_UI:2" --snap "MAIN - Rightfit 15s@4.5,9"
+playrig ae status <id>
+playrig ae tail
+```
+
+Root: `--root`, else `PLAYRIG_ROOT`, else `~/Documents/Playrig/ae`. Flags: `--id`, `--timeout <sec>` (default 120), `--no-undo`, `--json` (raw result).
+`playrig ae run` exits non-zero unless the status is `ok`.
+
+Without the CLI: write `inbox/<id>.jsx.tmp`, rename to `inbox/<id>.jsx` (optionally write `inbox/<id>.json` options first), then poll for `out/<id>/result.json`.
+
+Options JSON: `{"timeoutSec":120,"undoGroup":true,"snapshots":[{"comp":"X","times":[1,2]}],"inspect":{"comp":"X","depth":2,"time":0}}`
+
+`result.json` fields: `id, status (ok|error|timeout|rejected), startedAt, durationMs, aeVersion, project{path,dirty}, action, actionSource (declared|inferred), description, error{message,line,fileName,source}, log[], snapshots[{comp,time,file,ok}], inspect, returnValue`, plus `actionLabel` (recipe jobs), `backup` and `sync`.
+
+### Actions and descriptions
+
+Every job has one **action** from the defined list in `lib/actions.json` (shared data: the panel, the CLI and a later UXP port all read it). It is the table's *Action* column. Declare it in the first lines of the job, then add a one-line description (the summary under the table and "What happened" in the details):
+
+```js
+// @action layer.add
+// Added three null layers for the camera rig
+```
+
+or `playrig ae run job.jsx --action layer.add --desc "..."`. `playrig ae lib run <id>` sets `recipe.<id>` (label = the recipe's name) and the recipe summary itself. Undeclared jobs are classified from what the script calls (rules in `actions.json`, `inferBySource`) and shown as inferred; unknown ids show as "Custom action". Add a new entry to `actions.json` when a new kind of job appears.
+
+Actions: `bridge.test, project.inspect, frame.export, footage.import, comp.create, precomp.create, layer.add, layer.edit, text.edit, shape.edit, effect.add, animate.keyframes, expression.set, render.queue, recipe.run, scratch.baseline, scratch.cleanup, job.rejected, custom`, and `recipe.<id>`.
+
+`playrig ae tail` shows the latest jobs of the project of the most recent job (prints `Jobs for: <project>`); `--all` lists every project, `--project <name>` picks one.
+
+### PLAYRIG API in jobs (`BRIDGE` is kept as an alias)
+
+`PLAYRIG.log(msg)`, `PLAYRIG.comp(name)`, `PLAYRIG.snap(comp, time)`, `PLAYRIG.contactSheet(comp, start, end, step)`, `PLAYRIG.inspect(comp, depth, time)` (depth 0 = that comp only), `PLAYRIG.ret(value)`, `PLAYRIG.root`, `PLAYRIG.json.stringify/parse`.
+
+Rules for writing jobs are in `CLAUDE.md`.
+
+## Project-folder log (travels with the project)
+
+After every job the panel mirrors its work into `EDIT_LOGS/` next to the `.aep` (the same folder name the Playrig for Premiere Pro uses; an older `AE-BRIDGE/` folder is renamed to it on the first job after the update):
+
+```
+<project folder>/EDIT_LOGS/
+├── README.md       how to resume on another system
+├── JOURNAL.md      chronological record of every job: status, errors, log, snapshots
+├── jobs/           the exact <id>.jsx (+ <id>.json options) that ran
+├── results/<id>/   result.json + PNG snapshots
+└── assets.ae.md/.json  footage (relative paths, MISSING / EXTERNAL flags), comps and fonts, refreshed each job
+```
+
+(`assets.ae.*` is named so it never overwrites the Playrig for Premiere Pro's `assets.md` when a Premiere and an AE project share a folder; `JOURNAL.md` is shared and each entry says which job it is. The panel's table and `playrig ae tail` only list results whose `project.path` is the open project.)
+
+Move the whole project folder and a new session can read `JOURNAL.md` and `assets.ae.md` to see what was done and what is available. The root folder (`inbox/ out/ done/`) stays the transport; `EDIT_LOGS/` is the durable record. If the project has never been saved it has no folder: `result.sync` says so and the jobs are backfilled after the first job that runs on a saved project. Sync failures never fail a job; they are reported in `result.sync` (and by `aeb`). Footage outside the project folder is flagged EXTERNAL because it won't move with it; collect files into the project folder to make it portable.
+
+## Known limitations and notes
+
+- **Timeouts are advisory.** ExtendScript can't interrupt a running script. If a job runs longer than `timeoutSec`, it is marked `timeout` once it returns. An infinite loop freezes After Effects.
+- **Backups copy the saved file.** `app.project.save(File)` behaves like Save As and would re-point the open project at the backup, so the panel instead copies the project file on disk (`<root>/backups/<name>-<id>.aep`). The copy reflects the last save, not unsaved edits; `result.backup.reflectsUnsavedChanges` is `false`. Unsaved projects get no backup.
+- `project.dirty` is reported only if the scripting DOM exposes it; otherwise `null`.
+- Snapshots use `comp.saveFrameToPng` and then wait up to 10 s for the file to exist with non-zero size.
+- Closing the panel stops polling.
+- Project organization (folders/auto-filing, as in the Playrig for Premiere Pro) is deliberately **not** part of the Playrig for After Effects (decided with the user, 2026-10-02).
+- Jobs share one persistent ExtendScript engine (`#targetengine "playrig"`), so globals can leak between jobs.
+
+## Status of verification
+
+This was written without access to After Effects, so none of the After Effects-side behavior has been run yet. Please run the acceptance checks below on v26.x and note results here (in particular whether `saveFrameToPng` returns before the file is written, and whether `project.dirty` exists).
+
+1. `hello.jsx` → `ok` within ~2 s.
+2. A job with `throw new Error("boom")` → `error` with message, line and source.
+3. `snap.jsx` → non-empty, valid 1920×1080 PNG.
+4. Inspect your `04_UI` comp at depth 2 → panels, parents, key times, shape group order.
+5. A job adding 3 layers → one Edit → Undo removes all 3.
+6. A job calling `alert("x")` doesn't block; `x` appears in the log.
+7. `playrig ae run examples/snap.jsx --snap "Comp 1@0,1"` → prints paths, exit 0.
+8. A file named `bad name!.jsx` in `inbox/` → `rejected`, not run.
+
+## Still unverified (panel UX update, 2026-10-02)
+
+Written and unit-tested without driving After Effects' UI (AE 26.5 installed; the screen-control tool was unavailable). Verified: JS syntax of all panel/lib files, `panel-core.jsxinc` against a mock File/Folder (header parsing, inference, per-project history with 70 results from two projects, sorting, 50-row limit), `playrig ae tail/--action/--desc`. **Not yet seen in AE:** ScriptUI layout and spacing (docked and floating), the 3-column listbox with header and icons, `iconbutton` power/gear icons and 16 px PNGs on a retina display, `scheduleTask` project watcher, Settings dialog (path validation, Browse), details window sizing, `AE-BRIDGE/` -> `EDIT_LOGS/` rename on the first job, opening the About links. Needs a screenshot pass with the user.

package/editions/ae/client/aeb.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+'use strict';
+// Deprecated: `aeb` is now `playrig ae <command>`. Kept so old commands and scripts keep working; it prints a notice and forwards.
+const fs = require('fs');
+const path = require('path');
+const candidates = [path.join(__dirname, '..', '..', 'cli', 'lib', 'main.js'), path.join(__dirname, '..', '..', '..', 'lib', 'main.js')];
+const main = candidates.find((f) => fs.existsSync(f));
+if (!main) { console.error('aeb is deprecated and could not find the playrig CLI. Install it: npm install -g playrig'); process.exit(2); }
+require(main).legacy('ae', process.argv.slice(2));

package/editions/ae/examples/hello.jsx

@@ -0,0 +1,3 @@
+// @action bridge.test
+// Checks that Playrig can run a job (logs a greeting, changes nothing)
+PLAYRIG.log("hi from After Effects");

package/editions/ae/examples/inspect.jsx

@@ -0,0 +1,7 @@
+// @action project.inspect
+// Inspects the comp open in the viewer (depth 2) and returns the tree as the job's returnValue.
+var item = app.project.activeItem;
+if (!(item instanceof CompItem)) {
+    throw new Error("Open a comp in the viewer first, or edit this file to name one.");
+}
+PLAYRIG.ret(PLAYRIG.inspect(item.name, 2, item.time));

package/editions/ae/examples/snap.jsx

@@ -0,0 +1,15 @@
+// @action comp.create
+// Creates (or reuses) a 1920x1080 "Comp 1" with a red solid and snaps it at time 0.
+var comp = null, i, it;
+for (i = 1; i <= app.project.numItems; i++) {
+    it = app.project.item(i);
+    if (it instanceof CompItem && it.name === "Comp 1") { comp = it; break; }
+}
+if (!comp) {
+    comp = app.project.items.addComp("Comp 1", 1920, 1080, 1, 5, 30);
+    comp.layers.addSolid([1, 0, 0], "Red", 1920, 1080, 1, 5);
+    PLAYRIG.log("created Comp 1");
+} else {
+    PLAYRIG.log("reusing Comp 1");
+}
+PLAYRIG.snap("Comp 1", 0);

package/editions/ae/lib/actions.json

@@ -0,0 +1,159 @@
+{
+  "_about": "Shared, engine-neutral data for the Playrig for After Effects: read by the ExtendScript panel, by aeb (Node) and, later, by a UXP port. Plain JSON on purpose. Labels and summaries are display text only: renaming one renames it for every past and future job.",
+  "logFolder": "EDIT_LOGS",
+  "legacyLogFolder": "AE-BRIDGE",
+  "recipePrefix": "recipe.",
+  "actions": {
+    "bridge.test": {
+      "label": "Playrig test",
+      "summary": "Checked that Playrig can run a job. No project changes."
+    },
+    "project.inspect": {
+      "label": "Inspect project",
+      "summary": "Read comps, layers, effects or footage. No project changes."
+    },
+    "frame.export": {
+      "label": "Export frames",
+      "summary": "Saved still frames from a composition."
+    },
+    "footage.import": {
+      "label": "Import footage",
+      "summary": "Imported files into the project."
+    },
+    "comp.create": {
+      "label": "Create comp",
+      "summary": "Created a composition."
+    },
+    "precomp.create": {
+      "label": "Pre-compose layers",
+      "summary": "Moved layers into a new nested composition."
+    },
+    "layer.add": {
+      "label": "Add layers",
+      "summary": "Added solids, nulls, cameras, lights or footage layers to a comp."
+    },
+    "layer.edit": {
+      "label": "Edit layers",
+      "summary": "Moved, timed, parented, renamed or removed layers."
+    },
+    "text.edit": {
+      "label": "Edit text",
+      "summary": "Created or changed text layers."
+    },
+    "shape.edit": {
+      "label": "Edit shapes",
+      "summary": "Created or changed shape layers and their contents."
+    },
+    "effect.add": {
+      "label": "Add effects",
+      "summary": "Added or changed effects on layers."
+    },
+    "animate.keyframes": {
+      "label": "Animate (keyframes)",
+      "summary": "Set or changed keyframes."
+    },
+    "expression.set": {
+      "label": "Set expressions",
+      "summary": "Wrote or changed property expressions."
+    },
+    "render.queue": {
+      "label": "Render queue",
+      "summary": "Added items to or changed the render queue."
+    },
+    "recipe.run": {
+      "label": "Run recipe",
+      "summary": "Ran a recipe from the motion library."
+    },
+    "scratch.baseline": {
+      "label": "Check test items",
+      "summary": "Recorded or listed the temporary items created while experimenting. No project changes."
+    },
+    "scratch.cleanup": {
+      "label": "Clean up test items",
+      "summary": "Removed temporary comps and items created while experimenting."
+    },
+    "job.rejected": {
+      "label": "Rejected job",
+      "summary": "The job was refused before it ran."
+    },
+    "custom": {
+      "label": "Custom action",
+      "summary": "A job with no declared action."
+    }
+  },
+  "inferById": [
+    {
+      "re": "^scratch-clean",
+      "flags": "i",
+      "action": "scratch.cleanup"
+    },
+    {
+      "re": "^scratch-(start|status)",
+      "flags": "i",
+      "action": "scratch.baseline"
+    }
+  ],
+  "_inferNote": "Applied to the job script in order, first match wins. Jobs that carry the recipe machinery (__aebPre) are recipe.run. Declaring the action in the job header beats all of this.",
+  "inferBySource": [
+    {
+      "re": "__aebPre\\s*\\(",
+      "action": "recipe.run"
+    },
+    {
+      "re": "renderQueue\\.(add|item)",
+      "action": "render.queue"
+    },
+    {
+      "re": "\\.remove\\(\\)[\\s\\S]*(scratch|SCRATCH)",
+      "action": "scratch.cleanup"
+    },
+    {
+      "re": "\\.precompose\\s*\\(",
+      "action": "precomp.create"
+    },
+    {
+      "re": "importFile\\s*\\(|ImportOptions",
+      "action": "footage.import"
+    },
+    {
+      "re": "\\.addComp\\s*\\(",
+      "action": "comp.create"
+    },
+    {
+      "re": "\\.addText\\s*\\(|\\.addBoxText\\s*\\(|ADBE Text Document|TextDocument",
+      "action": "text.edit"
+    },
+    {
+      "re": "\\.addShape\\s*\\(|ADBE Vector",
+      "action": "shape.edit"
+    },
+    {
+      "re": "\\.expression\\s*=",
+      "action": "expression.set"
+    },
+    {
+      "re": "setValueAtTime|setValuesAtTimes|\\.addKey\\s*\\(|setTemporalEase",
+      "action": "animate.keyframes"
+    },
+    {
+      "re": "ADBE Effect Parade|addProperty\\s*\\(\\s*[\"']ADBE",
+      "action": "effect.add"
+    },
+    {
+      "re": "\\.addSolid\\s*\\(|\\.addNull\\s*\\(|\\.addCamera\\s*\\(|\\.addLight\\s*\\(|layers\\.add\\s*\\(",
+      "action": "layer.add"
+    },
+    {
+      "re": "\\.parent\\s*=|\\.startTime\\s*=|\\.inPoint\\s*=|\\.outPoint\\s*=|\\.moveTo\\w*\\(|\\.name\\s*=",
+      "action": "layer.edit"
+    },
+    {
+      "re": "hi from After Effects|(?:PLAYRIG|PLAYPILOT|BRIDGE)\\.log\\(\\s*[\"']hi",
+      "action": "bridge.test"
+    },
+    {
+      "re": "(?:PLAYRIG|PLAYPILOT|BRIDGE)\\.inspect|(?:PLAYRIG|PLAYPILOT|BRIDGE)\\.snap|(?:PLAYRIG|PLAYPILOT|BRIDGE)\\.contactSheet|numItems|numLayers",
+      "action": "project.inspect"
+    }
+  ]
+}