afterpresets 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,25 @@
+AfterPresets CLI and Runtime License
+
+Copyright (c) AfterPresets. All rights reserved.
+
+This package ("the Software") contains the AfterPresets command-line tool and
+the AfterPresets runtime.
+
+You may install and use the Software only to create, test, build and publish
+Adobe After Effects extensions that are distributed through AfterPresets
+(afterpresets.com), and you may include the runtime in those extensions as
+the Software's build process does.
+
+You may not, except as the law expressly allows:
+  - modify, decompile, deobfuscate or reverse engineer the runtime, or remove,
+    disable or work around its licensing, signing or update checks;
+  - copy or redistribute the Software, or the runtime outside an extension
+    built with the Software;
+  - use the Software to build or distribute extensions outside AfterPresets.
+
+Use of AfterPresets services is also governed by the AfterPresets Terms of
+Service at https://afterpresets.com.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL AFTERPRESETS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY ARISING FROM THE SOFTWARE OR ITS USE.

package/README.md

@@ -1,3 +1,21 @@
-# Temporary Holding Version
+# AfterPresets CLI
 
-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.
+Make Adobe After Effects extensions with an AI agent, and sell them on
+[AfterPresets](https://afterpresets.com) with licensing, signed auto-updates
+and checkout handled.
+
+You do not need to write code. Open an empty folder in your agent (the Code
+tab of the Claude desktop app, Claude Code, Codex, Cursor...) and follow the
+**[Quickstart](https://docs.afterpresets.com/get-started/quickstart/)**.
+
+```sh
+npx afterpresets login
+npx afterpresets init my-extension
+```
+
+Inside a project, `ap dev` puts the extension into After Effects and reloads
+it on every save, `ap push` publishes a release, and `ap upgrade` updates
+this package. Every project includes `AGENTS.md` and an MCP server
+(`ap mcp`) so your agent can see, click and test the live panel.
+
+Docs: https://docs.afterpresets.com

package/bin/ap.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+"use strict";const{main:r}=require("../src/cli"),{createContext:s}=require("../src/context");r(process.argv.slice(2),s()).then(e=>{process.exitCode=e});

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "afterpresets",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Create, develop, and publish Adobe CEP extensions on AfterPresets.",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://docs.afterpresets.com",
+  "keywords": [
+    "after effects",
+    "adobe",
+    "cep",
+    "extension",
+    "afterpresets",
+    "mcp"
+  ],
+  "bin": {
+    "ap": "bin/ap.js",
+    "afterpresets": "bin/ap.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "runtime",
+    "template",
+    "vendor",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "adm-zip": "0.5.16",
+    "chokidar": "3.6.0",
+    "esbuild": "0.25.12",
+    "jsxbin": "2.3.0",
+    "playwright-core": "1.64.1",
+    "typescript": "5.9.3"
+  },
+  "afterpresets": {
+    "runtimeVersion": "0.3.0"
+  }
+}

package/runtime/docs/README.md

@@ -0,0 +1,63 @@
+---
+title: AfterPresets runtime reference
+description: What the AfterPresets runtime does, and which reference file to read before you use any AP.* API.
+---
+
+# AfterPresets runtime reference
+
+These files are for the AI coding agent that builds an After Effects extension
+with AfterPresets. They describe the `AP.*` API that every panel gets.
+
+## What the runtime does
+
+The runtime is a small script that the AfterPresets CLI puts in front of each
+panel's JavaScript. It is logic only. It draws nothing: your project owns every
+screen, style, and word the user sees.
+
+It gives you:
+
+- `AP.boot` to start the panel.
+- Licensing, off by default. Paid extensions must turn it on.
+- Signed updates with changelogs.
+- `AP.host.eval` to call After Effects (ExtendScript) functions.
+- `AP.panels` and `AP.events` for extensions with more than one panel.
+- `AP.paths` to find the images, videos and other files you ship.
+- `AP.storage` to save settings and other small data on this computer.
+
+Do not edit the runtime and do not copy it into your source files. The CLI
+adds it for you. `ap docs` refreshes this folder from the installed runtime.
+
+## The rule
+
+**Read the relevant file below before you write or change code that uses
+`AP.*`.** Do not guess option names, statuses, or callback shapes. If a file
+and your memory disagree, the file wins.
+
+## Files
+
+| File | Read it before you |
+|---|---|
+| [boot.md](boot.md) | call `AP.boot`, use `ctx`, or change when the app starts |
+| [licensing.md](licensing.md) | turn licensing on, write `renderLicense`, or change the license screen |
+| [updates.md](updates.md) | change update options or the update screen, or show a changelog |
+| [host.md](host.md) | call After Effects from the panel or write `jsx/` code |
+| [panels.md](panels.md) | add a panel or modal, open/close panels, or send data between panels |
+| [assets.md](assets.md) | add images, fonts, videos or other files, or import a file into After Effects |
+| [storage.md](storage.md) | save settings, recent items or any other data between launches |
+
+## Commands you will use
+
+```sh
+ap dev                          # build, link into After Effects, rebuild on change
+ap check                        # static checks; also run by ap dev and ap push
+ap add panel settings --type modal
+ap push                         # publish a release (asks for version bump and changelog)
+ap docs                         # refresh docs/afterpresets/ from the runtime
+```
+
+## Compatibility
+
+Panels run in Adobe CEP 10 or later (After Effects 2020+). Its browser is old
+(Chromium 74 in CEP 10). Write plain ES5 in panel code: `var`, `function`, no
+arrow functions, no `let`/`const`, no `class`, no template strings, no
+`fetch`-only features. ExtendScript in `jsx/` is ES3 (see [host.md](host.md)).

package/runtime/docs/assets.md

@@ -0,0 +1,74 @@
+---
+title: Media and other files
+description: Where to put images, fonts, videos, presets and other files your extension ships, and how to use them from HTML, CSS, JavaScript and ExtendScript.
+---
+
+# Media and other files
+
+Put files your extension ships in these folders at the **project root**
+(next to `afterpresets.json`):
+
+```
+assets/   fonts/   icons/   images/   media/
+```
+
+They are copied into the build unchanged, at the same place: `media/intro.mp4`
+in the project is `media/intro.mp4` inside the installed extension. Other
+folders are not shipped. To choose your own list, set it in
+`afterpresets.json` (this replaces the defaults):
+
+```json
+"assets": ["media", "presets", "fonts"]
+```
+
+These files are **not** obfuscated or hidden. Anything the buyer installs, they
+can open. Keep secrets out of them. The whole release must stay under 200 MB.
+
+## From HTML and CSS
+
+Write paths relative to the file you are in, as usual. They must point into
+an asset folder; the build rewrites them for the installed extension and fails
+on a missing file.
+
+```html
+<!-- src/panels/main/index.html -->
+<img src="../../../images/logo.png" alt="">
+```
+
+```css
+/* src/features/home/home.css */
+.hero { background-image: url(../../../images/hero.jpg); }
+@font-face { font-family: "Brand"; src: url(../../../fonts/Brand.woff2); }
+```
+
+## From JavaScript
+
+Use `AP.paths`; never build paths by hand.
+
+| Call | Returns |
+|---|---|
+| `AP.paths.asset("media/intro.mp4")` | Absolute path of a shipped file. Relative path with `/`; `..` and absolute paths throw. |
+| `AP.paths.extension()` | Absolute path of the installed extension folder. |
+| `AP.paths.data()` | A writable folder for your own files. It survives updates. Never write into the extension folder: updates replace it. For settings use `AP.storage`; see [storage.md](storage.md). |
+
+## From ExtendScript (importing into After Effects)
+
+ExtendScript cannot see the panel's folders by itself. Pass the absolute path
+from the panel:
+
+```js
+// panel
+ctx.host.eval("importClip", [AP.paths.asset("media/intro.mp4")], function (result) {
+  if (result && result.error) { /* show result.error */ }
+});
+```
+
+```js
+// jsx/media.jsx (loaded automatically, like every .jsx file in jsx/)
+function importClip(path) {
+  var file = new File(path);
+  if (!file.exists) return JSON.stringify({ error: "Missing file: " + path });
+  var item = app.project.importFile(new ImportOptions(file));
+  return JSON.stringify({ ok: true, name: item.name });
+}
+```

package/runtime/docs/boot.md

@@ -0,0 +1,103 @@
+---
+title: AP.boot
+description: Start a panel with AP.boot. Options, the ctx object passed to start, and the boot lifecycle.
+---
+
+# AP.boot
+
+Every panel calls `AP.boot` exactly once, from its `src/panels/<id>/main.js`
+code. `ap check` fails when a panel never calls it.
+
+```js
+AP.boot({
+  start: function (ctx) {
+    // Build your UI here.
+  },
+  license: false,                              // default. true, or { offlineGraceDays, checkInBackground }
+  renderLicense: function (api, root) {},      // required when license is on
+  updates: { check: "auto", mode: "background" }   // defaults
+});
+```
+
+## Options
+
+| Option | Type | Default | Meaning |
+|---|---|---|---|
+| `start` | `function (ctx)` | required | Your app. Called once, when the panel may run. |
+| `license` | `false`, `true`, or `{ offlineGraceDays, checkInBackground }` | `false` | Turns licensing on. See [licensing.md](licensing.md). |
+| `renderLicense` | `function (api, root)` | none | Draws the license screen. Required when `license` is on. |
+| `updates.check` | `"auto"` or `"manual"` | `"auto"` | `"auto"` checks at start and every 6 hours. See [updates.md](updates.md). |
+| `updates.mode` | `"background"`, `"prompt"` or `"silent"` | `"background"` | What happens when an update is found. `"background"` installs it without asking, then your update screen offers **Reload now** (`AP.updates.reload()`). `"prompt"` waits for your Install button. `"silent"` installs and shows nothing. See [updates.md](updates.md). |
+
+Unknown values are replaced by the default with a console warning. If
+`license` is on and `renderLicense` is missing, `AP.boot` logs an error and
+throws; the panel stays empty.
+
+## ctx
+
+`start(ctx)` receives:
+
+```js
+ctx = {
+  product: { bundleId: "com.afterpresets.seller.tool", version: "1.2.0" },
+  panel:   { id: "main" },     // this panel's id from afterpresets.json
+  license: AP.license,         // license api; status is "disabled" when licensing is off
+  updates: AP.updates,         // see updates.md
+  host:    AP.host             // see host.md
+};
+```
+
+The same objects are also available as globals (`AP.license`, `AP.updates`,
+`AP.host`, `AP.panels`, `AP.events`) for code that runs outside `start`.
+
+## Lifecycle
+
+1. The page loads. The runtime is already defined; nothing has run yet.
+2. Your entry code calls `AP.boot(options)`.
+3. When the DOM is ready:
+   - **License off:** `AP.license.state.status` is `"disabled"` and `start(ctx)`
+     runs immediately.
+   - **License on:** the runtime adds an empty `<div id="ap-license-root">` to
+     `<body>`, calls `renderLicense(api, root)`, and validates the license.
+     `start(ctx)` runs once the status becomes `active` or `offline_grace`.
+     It never runs for any other status.
+4. After `start`, if `updates.check` is `"auto"`, the runtime checks for updates
+   now and every 6 hours. In the default `"background"` mode a found update is
+   installed right away and `AP.updates.onInstalled` fires; the panel keeps
+   running the old version until `AP.updates.reload()` or the next launch.
+
+`start` runs at most once per panel load. If the license later becomes invalid
+(for example the buyer signs out), the license root is shown again over your
+app; `start` is not called a second time.
+
+## Example: a free extension
+
+```js
+AP.boot({
+  start: function (ctx) {
+    var app = document.getElementById("app");
+    app.textContent = "Hello from " + ctx.product.bundleId + " (" + ctx.panel.id + ")";
+  }
+});
+```
+
+## Example: a paid extension
+
+```js
+AP.boot({
+  start: function (ctx) {
+    renderHome(document.getElementById("app"), ctx);   // imported from src/features/home/home.js
+  },
+  license: true,
+  renderLicense: renderLicense,               // imported; see licensing.md
+  updates: { check: "auto", mode: "background" }
+});
+```
+
+## Mistakes to avoid
+
+- Do not build app UI before `start` runs. Put it inside `start`.
+- Do not call `start` yourself, and do not call `AP.boot` twice (the second call
+  is ignored with a warning).
+- Do not wrap `AP.boot` in `try/catch` to hide the missing-`renderLicense`
+  error. Fix the options instead.

package/runtime/docs/host.md

@@ -0,0 +1,110 @@
+---
+title: Calling After Effects
+description: Call ExtendScript functions from a panel with AP.host.eval, write jsx/ functions in ES3 that return JSON, and handle host errors.
+---
+
+# Calling After Effects
+
+Panel code runs in a browser. Anything that touches After Effects (project,
+comps, layers, effects, files through `File`/`Folder`) runs in ExtendScript, in
+`jsx/`. `AP.host.eval` connects the two.
+
+## Where JSX lives
+
+Put ExtendScript in `jsx/`, one file per feature (for example
+`jsx/layers.jsx`; subfolders are fine). Every `.jsx` file there is loaded into
+After Effects once, before your app starts, and its functions are shared by
+all panels. Call one from panel code with `ctx.host.eval("fnName", [args], cb)`.
+
+- There is no list to keep: the CLI joins every `.jsx` file in alphabetical
+  path order, with JSON support (json2) first, embeds the result in every
+  panel's `main.js` (readable in `ap dev`, compiled to JSXBIN for releases),
+  and the runtime evaluates it as soon as `AP.boot` runs, before `start`.
+  Every `AP.host.eval` waits for that load.
+- Order only matters for code that runs at the top level of a file while it
+  loads (not inside a function). Keep files to function declarations.
+
+## Writing a JSX function
+
+ExtendScript is **ES3**: `var` only, no `let`/`const`, no arrow functions, no
+`Array.prototype.forEach`/`map`/`indexOf`, no `trim()`, no template strings.
+`JSON` is always available (the CLI adds json2).
+
+Rules:
+
+1. Declare a named top-level function. Avoid generic names; prefix them
+   (`myTool_addNull`), because every extension shares one ExtendScript engine.
+2. Take JSON-compatible arguments (strings, numbers, booleans, arrays, plain
+   objects).
+3. Return `JSON.stringify(...)`. Return a result object such as `{ ok: true, ... }`
+   or `{ ok: false, message: "..." }` for expected problems.
+4. Wrap changes to the project in `app.beginUndoGroup("Name")` /
+   `app.endUndoGroup()`.
+
+```js
+/* jsx/layers.jsx */
+function myTool_addNull(name) {
+    var comp = app.project.activeItem;
+    if (!comp || !(comp instanceof CompItem)) {
+        return JSON.stringify({ ok: false, message: "Select a composition first." });
+    }
+    app.beginUndoGroup("Add null");
+    try {
+        var layer = comp.layers.addNull();
+        layer.name = name;
+        return JSON.stringify({ ok: true, index: layer.index });
+    } finally {
+        app.endUndoGroup();
+    }
+}
+```
+
+## Calling it from the panel
+
+```js
+AP.host.eval("myTool_addNull", ["Controller"], function (result) {
+  if (!result || result.error) {
+    showError(result ? result.error : "No answer from After Effects.");
+    return;
+  }
+  if (!result.ok) {
+    showMessage(result.message);
+    return;
+  }
+  showMessage("Added layer " + result.index);
+});
+```
+
+`AP.host.eval(fnName, args, cb)`:
+
+- `fnName` is a function name or dotted path (`"myTool.addNull"`). Anything else
+  is refused with `{ error }`.
+- `args` is an array. Each value is passed as a JSON literal, so quotes,
+  newlines, and code in strings are safe. `undefined` becomes `null`.
+- `cb(result)` receives the parsed JSON your function returned, `null` when it
+  returned nothing, or `{ error: "message" }` when anything failed.
+
+Never build ExtendScript source by joining strings with user input. Always pass
+values through `args`.
+
+## Errors
+
+| `result` | Cause |
+|---|---|
+| `{ error: "<message>" }` | Your function threw; the message is the thrown error's message. |
+| `{ error: "...is undefined" }` or similar | The function does not exist: check the name, and that its file is in `jsx/` and ends in `.jsx`. |
+| `{ error: "The host returned a non-JSON result.", raw }` | Your function returned a plain string. Return `JSON.stringify(...)`. |
+| `{ error: "The host script failed to run." }` | ExtendScript syntax error or an ES5+ feature in `jsx/`. |
+| `{ error: "Could not load host script: ..." }` | The embedded JSX failed to load. Read the message; usually a syntax error. |
+
+The JSX loads once per page. During `ap dev` every save rebuilds and reloads
+the open panels, which loads the new JSX too; after an update,
+`AP.updates.reload()` does the same. The new functions replace the old ones.
+Functions removed from the new code stay defined in After Effects until it
+restarts, so never rely on a function being absent.
+
+## Testing
+
+Call the function from the live panel and check the result and the project
+state. Use a disposable project or a duplicate composition for anything that
+changes layers, effects, files, or project data.