afterpresets 0.1.0 → 0.3.0

package/runtime/docs/cep/host-after-effects.md

@@ -0,0 +1,57 @@
+---
+title: After Effects ExtendScript
+description: "Rules for ExtendScript in After Effects (jsx/aeft/): undo groups, the active composition, 1-based collections, and the version range."
+---
+
+# After Effects ExtendScript
+
+Read [host.md](host.md) first: it explains `AP.host.eval` and how `jsx/` is
+loaded. This page is about code that runs in After Effects. Put code that only
+makes sense in After Effects in `jsx/aeft/`.
+
+## Undo
+
+Wrap every change in one undo group so the user undoes the whole action with
+one Ctrl/Cmd+Z, and close it in `finally`:
+
+```js
+app.beginUndoGroup("Rename layers");
+try {
+    /* changes */
+} finally {
+    app.endUndoGroup();
+}
+```
+
+The MCP `host_eval` tool already wraps each call in an undo group named
+"AfterPresets MCP".
+
+## The active composition
+
+`app.project.activeItem` is often null or not a composition (a footage item, a
+folder, or nothing selected). Check before using it:
+
+```js
+var comp = app.project.activeItem;
+if (!comp || !(comp instanceof CompItem)) {
+    return JSON.stringify({ ok: false, message: "Open or select a composition first." });
+}
+```
+
+## Collections and times
+
+- Collections are 1-based: `comp.layer(1)`, `app.project.item(1)`,
+  `comp.selectedLayers[0]` (a plain array, 0-based).
+- Times are seconds (floating point). `comp.frameDuration` is one frame.
+
+## Versions
+
+The extension's range is `hosts[].minVersion` in afterpresets.json (default
+17.0, After Effects 2020). Check `parseFloat(app.version)` before using newer
+APIs and return `{ ok: false, message }` when they are missing.
+
+## Type hints
+
+`ap check --types` checks `jsx/` against the After Effects 26.0 declarations
+from types-for-adobe and lists likely mistakes. Hints can be wrong; confirm
+with the MCP `host_eval` tool before changing working code.

package/runtime/docs/cep/host-premiere.md

@@ -0,0 +1,84 @@
+---
+title: Premiere Pro ExtendScript
+description: "Rules for ExtendScript in Premiere Pro (jsx/ppro/): no undo groups, times in ticks, 0-based track and clip collections, no QE DOM, and the version range."
+---
+
+# Premiere Pro ExtendScript
+
+Read [host.md](host.md) first: it explains `AP.host.eval` and how `jsx/` is
+loaded. This page is about code that runs in Premiere Pro. Put code that only
+makes sense in Premiere Pro in `jsx/ppro/`.
+
+## No undo groups
+
+Premiere Pro's ExtendScript has no `beginUndoGroup`. Every change a script
+makes (a clip moved, a marker added, a property set) is its own step in
+Edit → Undo. Keep scripted edits small, do the checks before the first change,
+and tell the user how many undo steps an action adds. The MCP `host_eval`
+tool cannot group them either.
+
+## The active sequence
+
+`app.project.activeSequence` is null when no sequence is open. Check it:
+
+```js
+function myTool_sequenceInfo() {
+    var sequence = app.project.activeSequence;
+    if (!sequence) return JSON.stringify({ ok: false, message: "Open a sequence first." });
+    var clips = 0;
+    for (var i = 0; i < sequence.videoTracks.numTracks; i++) {
+        clips += sequence.videoTracks[i].clips.numItems;
+    }
+    return JSON.stringify({ ok: true, name: sequence.name, videoClips: clips });
+}
+```
+
+## Collections
+
+Tracks, clips, sequences and project items are 0-based collections with a
+count property: `sequence.videoTracks[0]` with `numTracks`,
+`track.clips[0]` with `numItems`, `app.project.sequences[0]` with
+`numSequences`, `app.project.rootItem.children[0]` with `numItems`. Use a
+`for` loop; they are not arrays.
+
+## Times are ticks
+
+Premiere measures time in ticks: **254016000000 ticks per second**. A `Time`
+object has `.seconds` (a number) and `.ticks` (a string). Create one with
+`new Time()` and set either:
+
+```js
+var t = new Time();
+t.seconds = 2.5;
+app.project.activeSequence.setPlayerPosition(t.ticks);   // move the playhead to 2.5 s
+var startSeconds = clip.start.seconds;                   // read a clip's start
+```
+
+Frame-accurate maths: convert with the sequence's timebase
+(`sequence.timebase`, ticks per frame, a string) instead of rounding seconds.
+
+## Things not to use
+
+- **The QE DOM** (`app.enableQE()`, `qe.*`): undocumented, unsupported, and
+  it changes between versions. Do not ship code that needs it.
+- Dialogs (`alert`, `confirm`, `File.openDialog`) block Premiere Pro while
+  open; the panel can show its own UI instead.
+
+## Projects
+
+- `app.project` is the active project. Premiere Pro can have several projects
+  open (`app.projects`, `numProjects`).
+- Save with `app.project.save()`. The MCP `host_scratch_project` tool creates a
+  new project in the temp folder and leaves the user's project open.
+
+## Versions
+
+The extension's range is `hosts[].minVersion` in afterpresets.json (default
+14.0, Premiere Pro 2020). Check `app.version` before using newer APIs and
+return `{ ok: false, message }` when they are missing.
+
+## Type hints
+
+`ap check --types` checks `jsx/` against the Premiere Pro 24.0 declarations
+from types-for-adobe (the newest set; newer APIs may be missing) and lists
+likely mistakes. Hints can be wrong; confirm with the MCP `host_eval` tool.

package/runtime/docs/{host.md → cep/host.md}

@@ -1,21 +1,46 @@
 ---
-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.
+title: Calling the app (ExtendScript)
+description: Call ExtendScript functions in After Effects or Premiere Pro from a panel with AP.host.eval, write jsx/ functions in ES3 that return JSON, keep app-only code in jsx/aeft/ and jsx/ppro/, and handle host errors.
 ---
 
-# Calling After Effects
+# Calling the app (ExtendScript)
 
-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.
+Panel code runs in a browser. Anything that touches the app (the project, its
+compositions or sequences, layers or clips, files through `File`/`Folder`) runs
+in ExtendScript, in `jsx/`. `AP.host.eval` connects the two. It works the same
+in After Effects and Premiere Pro. What you can do in each app:
+
+- [host-after-effects.md](host-after-effects.md): After Effects
+- [host-premiere.md](host-premiere.md): Premiere Pro
 
 ## 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
+the app 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)`.
 
+Two folders are special (afterpresets.json `hosts` lists the apps):
+
+| Folder | Loaded in |
+|---|---|
+| `jsx/aeft/` | After Effects only |
+| `jsx/ppro/` | Premiere Pro only |
+| everything else in `jsx/` | every app the extension targets |
+
+An extension for both apps can define the same function in `jsx/aeft/` and
+`jsx/ppro/` (for example `myTool_activeItemName`) and call it from shared panel
+code; each app loads its own version. `ap check` warns about a folder for an
+app the project does not target.
+
+`AP.host.app` (also `ctx.host.app`) is the app running the panel: `"AEFT"`
+(After Effects) or `"PPRO"` (Premiere Pro). Use it for wording that differs
+between the apps, or to hide a feature that only one app has:
+
+```js
+var noun = ctx.host.app === "PPRO" ? "sequence" : "composition";
+```
+
 - 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),
@@ -38,11 +63,11 @@ Rules:
    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()`.
+4. Undo: in After Effects wrap changes in one undo group; Premiere Pro has
+   none (every change is its own undo step). See the app pages.
 
 ```js
-/* jsx/layers.jsx */
+/* jsx/aeft/layers.jsx (After Effects) */
 function myTool_addNull(name) {
     var comp = app.project.activeItem;
     if (!comp || !(comp instanceof CompItem)) {
@@ -64,7 +89,7 @@ function myTool_addNull(name) {
 ```js
 AP.host.eval("myTool_addNull", ["Controller"], function (result) {
   if (!result || result.error) {
-    showError(result ? result.error : "No answer from After Effects.");
+    showError(result ? result.error : "No answer from the app.");
     return;
   }
   if (!result.ok) {
@@ -92,19 +117,20 @@ values through `args`.
 | `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: "...is undefined" }` or similar | The function does not exist: check the name, that its file is in `jsx/` and ends in `.jsx`, and that it is not in another app's folder (`jsx/aeft/`, `jsx/ppro/`). |
 | `{ 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. |
+| `{ error: "Could not load host script: ..." }` | The embedded JSX failed to load. Read the message; usually a syntax error. "This extension has no host script for X" means the build has no code for the running app (afterpresets.json `hosts`). |
 
 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
+Functions removed from the new code stay defined in the app 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.
+state. Use a disposable project (the MCP `host_scratch_project` tool) for
+anything that changes the project. With the MCP tools, `host_eval` runs in the
+app that runs the connected panel.

package/runtime/docs/{README.md → common/README.md}

@@ -5,8 +5,8 @@ description: What the AfterPresets runtime does, and which reference file to rea
 
 # 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.
+These files are for the AI coding agent that builds an After Effects or Premiere
+Pro extension with AfterPresets. They describe the `AP.*` API that every panel gets.
 
 ## What the runtime does
 
@@ -17,9 +17,9 @@ 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.
+- Licensing, off in `AP.boot` by default (the starter project turns it on). Paid extensions must keep it on.
 - Signed updates with changelogs.
-- `AP.host.eval` to call After Effects (ExtendScript) functions.
+- `AP.host.eval` to call ExtendScript functions in the app (After Effects or Premiere Pro).
 - `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.
@@ -40,15 +40,17 @@ and your memory disagree, the file wins.
 | [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 |
+| [host.md](host.md) | call the app from the panel or write `jsx/` code |
+| [host-after-effects.md](host-after-effects.md) | write ExtendScript for After Effects (`jsx/aeft/`) |
+| [host-premiere.md](host-premiere.md) | write ExtendScript for Premiere Pro (`jsx/ppro/`) |
 | [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 |
+| [assets.md](assets.md) | add images, fonts, videos or other files, or import a file into the app |
 | [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 dev                          # build, link into the app, 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)
@@ -57,7 +59,7 @@ ap docs                         # refresh docs/afterpresets/ from the runtime
 
 ## Compatibility
 
-Panels run in Adobe CEP 10 or later (After Effects 2020+). Its browser is old
+Panels run in Adobe CEP 10 or later (After Effects 2020+, Premiere Pro 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 → common/assets.md}

@@ -51,7 +51,7 @@ Use `AP.paths`; never build paths by hand.
 | `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)
+## From ExtendScript (importing into the app)
 
 ExtendScript cannot see the panel's folders by itself. Pass the absolute path
 from the panel:
@@ -64,7 +64,7 @@ ctx.host.eval("importClip", [AP.paths.asset("media/intro.mp4")], function (resul
 ```
 
 ```js
-// jsx/media.jsx (loaded automatically, like every .jsx file in jsx/)
+// After Effects: jsx/aeft/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 });
@@ -72,3 +72,17 @@ function importClip(path) {
   return JSON.stringify({ ok: true, name: item.name });
 }
 ```
+
+```js
+// Premiere Pro: jsx/ppro/media.jsx
+function importClip(path) {
+  var file = new File(path);
+  if (!file.exists) return JSON.stringify({ error: "Missing file: " + path });
+  // importFiles(paths, suppressUI, targetBin, importAsNumberedStills)
+  var ok = app.project.importFiles([file.fsName], true, app.project.getInsertionBin(), false);
+  return JSON.stringify({ ok: ok === true, name: file.name });
+}
+```
+
+Both files define the same function name: an extension for both apps calls
+`importClip` and each app loads its own version.

package/runtime/docs/{licensing.md → common/licensing.md}

@@ -35,7 +35,7 @@ once.
 
 After a successful online check the API returns a signed record of it, valid
 for 12 hours, and the runtime saves it with the token. Until it runs out,
-launching After Effects, reloading a panel (including `ap dev` reloads) or
+launching the app, reloading a panel (including `ap dev` reloads) or
 opening another panel unlocks straight away, with no network call and no
 `checking` screen. After 12 hours the license is checked online again, without blocking the
 buyer:

package/runtime/docs/{panels.md → common/panels.md}

@@ -12,9 +12,9 @@ HTML, and JavaScript. They share `js/`, `css/`, `jsx/`, and the license.
 
 | `type` | What it is | Use it for |
 |---|---|---|
-| `panel` | A dockable After Effects panel, listed in **Window → Extensions** when `menu` is true | The main UI |
-| `modal` | A dialog that blocks After Effects until closed | Settings, confirmations, one-off forms |
-| `invisible` | No window; starts with After Effects and runs in the background | Listening for events, background work |
+| `panel` | A dockable panel, listed in **Window → Extensions** when `menu` is true | The main UI |
+| `modal` | A dialog that blocks the app until closed | Settings, confirmations, one-off forms |
+| `invisible` | No window; starts with the app and runs in the background | Listening for events, background work |
 
 Panels are declared in `afterpresets.json`:
 
@@ -37,7 +37,7 @@ This creates `src/panels/<id>/index.html` and `src/panels/<id>/main.js`, and
 adds the entry to `afterpresets.json`. Each panel calls `AP.boot` in its own
 `main.js` and imports the screens and helpers it uses from `src/features/`
 and `src/shared/`. After adding a panel, restart
-`ap dev` and then After Effects: CEP reads the manifest only at launch.
+`ap dev` and then the app: CEP reads the manifest only at launch.
 
 ## AP.panels
 
@@ -49,7 +49,7 @@ AP.panels.close("settings");  // ask another open panel to close itself
 ```
 
 - Ids are the ones in `afterpresets.json`. An invalid id throws.
-- `open` asks After Effects to open the extension `<bundleId>.<id>`. It returns
+- `open` asks the app to open the extension `<bundleId>.<id>`. It returns
   `true` when the request was sent; it does not wait for the panel to load.
 - Data cannot be passed to `open`. Send it with `AP.events` once the other
   panel is ready (see "Handshake" below).

package/runtime/docs/{storage.md → common/storage.md}

@@ -1,6 +1,6 @@
 ---
 title: Saving data
-description: Where an extension keeps settings and other local state with AP.storage and AP.paths.data(), what goes inside the After Effects project instead, and what never to store.
+description: Where an extension keeps settings and other local state with AP.storage and AP.paths.data(), what goes inside the app's project file instead, and what never to store.
 ---
 
 # Saving data
@@ -11,7 +11,7 @@ description: Where an extension keeps settings and other local state with AP.sto
 |---|---|
 | Settings, preferences, recent items, small caches | `AP.storage` (below) |
 | Bigger files you create or download (images, media, generated presets) | A file in `AP.paths.data()` |
-| Data that belongs to one After Effects project | Inside the `.aep`, from `jsx/` (it travels with the project file) |
+| Data that belongs to one After Effects or Premiere Pro project | Inside the `.aep` / `.prproj`, from `jsx/` (it travels with the project file) |
 | Secrets (passwords, API keys, tokens) | Nowhere. Everything above is a plain file the user can open. |
 
 Do **not** use `localStorage`, `sessionStorage` or IndexedDB: in CEP each panel
@@ -71,12 +71,12 @@ var path = require("path");
 var file = path.join(AP.paths.data(), "thumbnails", "intro.png");
 ```
 
-Pass such paths to ExtendScript as arguments when After Effects needs them
+Pass such paths to ExtendScript as arguments when the app needs them
 (see [assets.md](assets.md)).
 
-## Inside the After Effects project
+## Inside the project file
 
 Data about one project (which presets it uses, a layout you applied) belongs in
-the project, not on the computer: it should follow the `.aep` to another
+the project, not on the computer: it should follow the `.aep` or `.prproj` to another
 machine. Read and write it from a `jsx/` function, for example in a project
 XMP field or on a layer or comp comment, and call it with `ctx.host.eval`.

package/runtime/docs/{updates.md → common/updates.md}

@@ -230,7 +230,7 @@ callback only.
 | `dev_build` | `ap dev` builds never install updates | Expected during development. Do not show the failure popup. |
 | `busy` | Another install is running | Try again later. |
 | `bad_signature`, `bad_checksum`, `bad_zip`, `bad_update_info` | The download failed verification; nothing was installed | Show the failure popup. Do not retry in a loop. |
-| `verify_unsupported` | After Effects is too old to verify signatures | Show the failure popup (reinstall from the product page). |
+| `verify_unsupported` | The app is too old to verify signatures | Show the failure popup (reinstall from the product page). |
 | `download_failed`, `install_failed` | Download or copy failed (the previous version is restored) | Show the failure popup. |
 
 ## Channels

package/runtime/docs/native/README.md

@@ -0,0 +1,44 @@
+---
+title: AfterPresets native effect reference
+description: Which file to read before writing or changing a C++ After Effects effect plugin built with AfterPresets.
+---
+
+# AfterPresets native effect reference
+
+These files are for the AI coding agent that builds an After Effects effect
+plugin (C++, Adobe's effect SDK) with AfterPresets. An effect is a new entry
+in the Effect menu that renders pixels, like a glow or a blur.
+
+## The rule
+
+**Read [rules.md](rules.md) before you write or change any effect code, and
+follow [testing.md](testing.md) before you say a change is done.** Then read
+the SDK topic files for your task (index: [sdk/README.md](sdk/README.md)). Do
+not guess struct fields, flag names, selectors or call order. If a file and
+your memory disagree, the file wins. If the SDK guide and the SDK headers in
+the project disagree, the headers win.
+
+## Files
+
+| File | Read it before you |
+|---|---|
+| [rules.md](rules.md) | write or change any effect code: the hard rules, each with why and an example |
+| [testing.md](testing.md) | say "done": build, apply the effect in After Effects, render frames and look at them |
+| [debugging.md](debugging.md) | chase a crash, an effect that does not load, wrong pixels, or a slow render |
+| [sdk/README.md](sdk/README.md) | use any part of the After Effects SDK: tasks mapped to small topic files |
+
+## About sdk/
+
+`sdk/` is Adobe's After Effects C++ SDK guide, cut into small topic files. It
+is generated on this computer from a pinned version of the community copy at
+https://github.com/docsforadobe/after-effects-plugin-guide. AfterPresets does
+not ship it: the guide is copyright Adobe. Never copy its text into the
+product, its listing or its source files. Search it with:
+
+```sh
+grep -rn "PF_OutFlag2_SUPPORTS_THREADED_RENDERING" docs/afterpresets/sdk/
+```
+
+Adobe's SDK itself (headers, samples, `Util/` helpers) is not redistributed
+either. The project gets it from Adobe; never commit it to a public
+repository.

package/runtime/docs/native/debugging.md

@@ -0,0 +1,140 @@
+---
+title: Debugging a native effect
+description: Find out why an effect does not load, crashes, renders wrong pixels or is slow, without an IDE - scripting checks, binary checks, crash reports, logs and debugger limits.
+---
+
+# Debugging a native effect
+
+You have no IDE and usually no debugger attached. Work from evidence you can
+collect yourself: scripting queries through `host_eval`, frames from
+`comp_capture`, the built binary, crash reports and logs. Change one thing at
+a time and test again ([testing.md](testing.md)).
+
+## The effect does not appear or does not apply
+
+1. **Is it loaded?** Ask After Effects for its effect list:
+
+   ```js
+   var out = [];
+   for (var i = 0; i < app.effects.length; i++) {
+       var e = app.effects[i];
+       if (/ACME/.test(e.matchName)) out.push(e.matchName + " | " + e.displayName + " | " + e.category);
+   }
+   return out.join("\n") || "not loaded";
+   ```
+
+   Listed, but `addProperty` fails: you are using a different match name.
+   Not listed: After Effects did not load the binary; go on.
+2. **Was After Effects restarted** after the binary was installed? Plugins
+   load at launch only.
+3. **Is it where After Effects looks?** See
+   [sdk/where-installers-should-put-plug-ins.md](sdk/where-installers-should-put-plug-ins.md).
+   Folders whose names end in parentheses, or start with `¬` (macOS) or `~`
+   (Windows), are not scanned. `ap dev` installs into
+   `/Library/Application Support/Adobe/Common/Plug-ins/7.0/MediaCore/AfterPresets Dev/<bundleId>/`,
+   a folder made once with administrator rights and then owned by the user;
+   buyers' copies go to `MediaCore/AfterPresets/<bundleId>/`. Any other
+   write to the shared MediaCore folder or the After Effects `Plug-ins`
+   folder needs administrator rights: ask the user, never use `sudo`
+   yourself.
+4. **Check the binary** (macOS):
+
+   ```sh
+   lipo -info Effect.plugin/Contents/MacOS/Effect     # arm64 and x86_64 for a universal build
+   nm -gU Effect.plugin/Contents/MacOS/Effect         # the entry point must be exported
+   codesign -dv Effect.plugin                         # must be signed (ad-hoc is enough to develop)
+   xattr -l Effect.plugin                             # com.apple.quarantine set by downloads
+   ```
+
+   macOS 15 and later refuse unsigned plugins; sign development builds
+   ad-hoc with `codesign --force --deep --sign - Effect.plugin`, and do not
+   touch the bundle after signing. The PiPL needs an entry point for every
+   architecture you build (`CodeMacARM64`, `CodeMacIntel64`, `CodeWin64X86`).
+5. **Check the PiPL against GlobalSetup**: flags (rule 2 in
+   [rules.md](rules.md)), match name, version. A mismatch warning appears when
+   the effect is applied; ask the user to read you any dialog.
+6. **Read After Effects' plugin loading log.** It is rewritten at every
+   launch: `~/Library/Preferences/Adobe/After Effects/<version>/Plugin Loading.log`
+   (for example `26.2`). Search it for your bundle name:
+
+   ```sh
+   grep -n -i "MyEffect" ~/Library/Preferences/Adobe/After\ Effects/*/Plugin\ Loading.log
+   ```
+
+   The line "No loaders recognized this plugin … Ignore" is normal for After
+   Effects effects (it comes from the shared MediaCore loader). A missing
+   line means After Effects never saw the file (wrong folder, not
+   restarted); a load error points at the binary (step 4) or the PiPL
+   (step 5).
+
+Whether a plugin loads also depends on how After Effects itself is signed
+(hardened runtime, library validation). A result on one computer, for
+example one with a re-signed or developer copy of After Effects, may not
+match a customer's computer.
+
+## After Effects crashes
+
+- macOS writes a crash report to `~/Library/Logs/DiagnosticReports/`
+  (`Adobe After Effects*.ips`). Find the crashed thread and look for frames in
+  your binary. Build development versions with debug symbols (`-g`) and keep
+  the `.dSYM`, so addresses map to functions and lines (`atos -o
+  Effect.plugin.dSYM/Contents/Resources/DWARF/Effect -arch arm64 -l <load
+  address> <address>`).
+- Usual causes: reading past a row (`rowbytes`, wrong pixel type for the
+  depth), an exception leaving the entry point (rule 15), a world used after
+  `PF_DisposeWorld`, writing shared state from several render threads
+  (rule 11), unbalanced parameter checkouts (rule 10).
+- After a crash, After Effects may show a recovery dialog at the next launch.
+  Ask the user to answer it; do not script around it.
+
+## Wrong pixels
+
+- Capture the same frame at 8, 16 and 32 bpc. Wrong in one depth only: that
+  depth's code path or its maximum channel value (32768 for 16 bpc).
+- Bright random colours, rainbows, black blotches: integer overflow; clamp
+  before converting.
+- Wrong only at half resolution or with an effect before yours: downsample
+  factors or buffer origin ([rules.md](rules.md), rule 9).
+- To see an internal value, temporarily write it into the output (for example
+  a red channel proportional to the value) and capture the frame. Remove it
+  afterwards.
+- Unchanged after a rebuild: After Effects still runs the old binary
+  (restart), or you looked at a cached frame (`comp_capture` clears caches by
+  default; keep it that way).
+
+## Slow renders
+
+`comp_capture` reports a render time per frame, measured after clearing the
+caches. Compare before and after a change on the same frames. Typical fixes:
+precompute tables once (GlobalSetup or SequenceSetup), avoid `pow`/`sqrt`/
+division per pixel, fuse passes, process only the requested area, and enable
+multi-frame rendering when the effect is thread-safe (rule 11).
+
+## Logs
+
+The AfterPresets native runtime (`ap_native`) writes a small log for each
+plugin: `~/Library/Logs/AfterPresets/<bundleId>.log` on macOS (rotated at
+1 MB; `ap_log_path()` returns the exact path). Each After Effects start adds
+a `start <bundleId> <version> build=...` line, then licence and update
+events. Read it with `tail -n 50`. It is safe to read: tokens and URL query
+strings are scrubbed.
+
+To log from effect code, call `ap_log(rt, level, "message")`: it never
+blocks and does no file I/O on the calling thread, so it is allowed in
+render code, but never log from inside the per-pixel loop. Never log licence
+tokens, account data or user paths, and remove temporary logging before
+release.
+
+## Debuggers
+
+Attaching `lldb` to a release build of After Effects 26.5 or later on macOS is
+refused because of how the application is signed. Adobe's workaround (a
+re-signed copy, or developer mode for beta builds) needs the user and
+administrator rights: see [sdk/debugging-ae-macos.md](sdk/debugging-ae-macos.md).
+Prefer the evidence above; propose a debugger session to the user only when
+it is the only way forward.
+
+Holding Cmd+Opt+Shift (macOS) or Ctrl+Alt+Shift (Windows) while After Effects
+starts resets its preferences, which clears settings a plugin may have
+stored. Only the user should do this, after being told it resets all their
+preferences.