afterpresets 0.1.0 → 0.3.0

package/runtime/docs/native/rules.md

@@ -0,0 +1,402 @@
+---
+title: Rules for native effects
+description: The hard rules and classic mistakes of After Effects effect plugins (PiPL, flags, match names, parameters, bit depths, Smart Render, multi-frame rendering, sequence data, memory, errors), each with why and an example.
+---
+
+# Rules for native effects
+
+Read this before writing or changing effect code. Each rule says why it
+exists and shows the right shape. Details are in the SDK topic files
+([sdk/README.md](sdk/README.md)); `grep` them for any name used here.
+
+## Identity and registration
+
+### 1. The match name is permanent, unique and prefixed
+
+The match name (`AE_Effect_Match_Name` in the PiPL, and the `matchName` given
+to `PF_REGISTER_EFFECT*` if the project registers in code) is the effect's
+identity. After Effects stores it in every project, preset and template that
+uses the effect. Give it a vendor prefix, keep it ASCII, and never change it
+after the first release. The display name and category may change; the match
+name may not.
+
+Why: rename it and every saved project shows "missing effect". Two vendors
+with the same match name collide, and one of the effects does not load.
+
+```c
+AE_Effect_Match_Name { "ACME Soft Glow" },   // never changes
+Name                 { "Soft Glow" },        // display name, up to 47 characters
+Category             { "ACME" },             // spelled the same in every effect
+```
+
+A category spelled two ways ("ACME" and "ACME ") makes two folders in the
+Effect menu.
+
+### 2. The PiPL flags equal the GlobalSetup flags
+
+`AE_Effect_Global_OutFlags` and `AE_Effect_Global_OutFlags_2` in the PiPL must
+be exactly the values `PF_Cmd_GLOBAL_SETUP` puts in `out_data->out_flags` and
+`out_data->out_flags2`. Every time you add or remove a flag (Smart Render,
+float, multi-frame rendering, `I_DO_DIALOG`, GPU...), change both.
+
+Why: After Effects reads the PiPL without running the plugin and reads the
+flags again at GlobalSetup. When they differ it warns the user when the effect
+is applied, and features silently follow the wrong set. This is the most
+common native-plugin mistake.
+
+```cpp
+// GlobalSetup
+out_data->out_flags  = PF_OutFlag_DEEP_COLOR_AWARE | PF_OutFlag_PIX_INDEPENDENT;
+out_data->out_flags2 = PF_OutFlag2_SUPPORTS_SMART_RENDER
+                     | PF_OutFlag2_FLOAT_COLOR_AWARE
+                     | PF_OutFlag2_SUPPORTS_THREADED_RENDERING;
+```
+
+The PiPL holds the same two numbers in hex. Keep both in one place: in an
+AfterPresets project the flags live only in `effect.json`, and the build
+generates both the PiPL and `ap_effect_config.h`, whose macros GlobalSetup
+uses; `ap check` compares the built PiPL with `effect.json`. Never type flag
+values by hand, and never edit a generated file.
+
+### 3. Versions agree and only go up
+
+`out_data->my_version` (set with `PF_VERSION(...)` in GlobalSetup) and
+`AE_Effect_Version` in the PiPL describe the same version: generate both from
+one header. Raise it for every release. `AE_Effect_Spec_Version` is the SDK
+version the effect was built with: use the SDK's `PF_AE_PLUG_IN_VERSION` /
+`PF_AE_PLUG_IN_SUBVERS` constants, never hand-typed numbers.
+
+Why: users and support read the version in the Effects panel and in "About".
+Multi-frame rendering needs an effect built against SDK 13.25 or later
+(March 2021 SDK or newer).
+
+```cpp
+out_data->my_version = PF_VERSION(MAJOR_VERSION, MINOR_VERSION, BUG_VERSION,
+                                  STAGE_VERSION, BUILD_VERSION);
+```
+
+### 4. One effect per binary, one entry point
+
+Ship one PiPL and one effect per `.plugin` / `.aex`. Export only the entry
+point (`EffectMain`, plus the SDK's `PluginDataEntryFunction*` when the effect
+also registers in code with `PF_REGISTER_EFFECT*`); hide every other symbol.
+
+Why: Premiere Pro and other hosts do not support several effects in one
+binary, and an update then has to replace all of them. Exported symbols from
+two plugins that share a library clash at load time (see
+[sdk/symbol-export.md](sdk/symbol-export.md)).
+
+## Parameters
+
+### 5. Parameter disk IDs never change, never get reused
+
+Each parameter has two numbers: its index (its position in the Effect
+Controls, the order you call `PF_ADD_*`) and its disk ID (`def.uu.id`, saved
+in projects). Keep two enums. Disk IDs start at 1. Add new IDs only at the
+end. Never delete, reorder or reuse an ID, even when you remove the
+parameter.
+
+Why: projects store values by disk ID. Reorder the IDs and a saved project
+loads "Radius" into "Intensity". Without IDs, After Effects numbers
+parameters by position, so inserting one shifts every later value.
+
+```cpp
+enum { GLOW_INPUT = 0, GLOW_RADIUS, GLOW_INTENSITY, GLOW_COLOR, GLOW_NUM_PARAMS };
+enum { RADIUS_DISK_ID = 1, INTENSITY_DISK_ID, COLOR_DISK_ID /* add new IDs here only */ };
+```
+
+Changing a parameter's default also needs care: give it a new disk ID, or set
+`PF_ParamFlag_USE_VALUE_FOR_OLD_PROJECTS`, so old projects keep the value they
+were made with. See [sdk/changing-parameter-orders.md](sdk/changing-parameter-orders.md).
+
+### 6. Clear every definition, count every parameter
+
+Call `AEFX_CLR_STRUCT(def)` before every `PF_ADD_*`, and set
+`out_data->num_params` to the number of parameters including the input layer
+(index 0).
+
+Why: a definition left over from the previous parameter carries flags and
+ranges into the next one. A wrong `num_params` makes the effect fail to apply
+or read garbage.
+
+```cpp
+PF_ParamDef def;
+AEFX_CLR_STRUCT(def);
+PF_ADD_FLOAT_SLIDERX("Radius", 0, 1000, 0, 200, 25, PF_Precision_TENTHS, 0, 0, RADIUS_DISK_ID);
+AEFX_CLR_STRUCT(def);
+PF_ADD_FLOAT_SLIDERX("Intensity", 0, 400, 0, 200, 100, PF_Precision_TENTHS, 0, 0, INTENSITY_DISK_ID);
+out_data->num_params = GLOW_NUM_PARAMS;
+```
+
+### 7. Read each parameter through its own union member
+
+| Parameter | Read |
+|---|---|
+| Float slider (`PF_ADD_FLOAT_SLIDERX`) | `u.fs_d.value` (double) |
+| Slider (int) | `u.sd.value` |
+| Fixed slider, percent | `u.fd.value` (`PF_Fixed`, 16.16: use `FIX2FLT`) |
+| Angle | `u.ad.value` (`PF_Fixed` degrees) |
+| Checkbox | `u.bd.value` |
+| Popup | `u.pd.value` (1-based) |
+| Color | `u.cd.value` (`PF_Pixel`, 8 bpc; use `PF_ColorParamSuite1` for float) |
+| Point | `u.td.x_value`, `u.td.y_value` (`PF_Fixed` pixels; use `PF_PointParamSuite1` for float) |
+| Layer | `u.ld` (checked out, see rule 10) |
+
+Why: the union does not complain. Reading a percent parameter through `sd`
+gives silently wrong numbers. Check the type in
+[sdk/parameters.md](sdk/parameters.md) before reading.
+
+`PF_ADD_POINT` defaults are a percentage of the layer (50, 50 is the
+centre), not pixels; the value you read back is in pixels of the layer. The
+values you get are already scaled for downsampling and origin offsets; see
+[sdk/parameters.md](sdk/parameters.md#point-parameter-origin).
+
+## Pixels and bit depths
+
+### 8. Handle every bit depth you declare, and declare what you handle
+
+- 8 bpc: `PF_Pixel`, channels 0-255. Always supported.
+- 16 bpc: `PF_Pixel16`, channels **0-32768** (`PF_MAX_CHAN16`), not 65535 and
+  not 32767. Declare with `PF_OutFlag_DEEP_COLOR_AWARE`.
+- 32 bpc: `PF_PixelFloat`, nominally 0.0-1.0, but values below 0 and above 1
+  are valid (overbright) and must not be clamped. Declare with
+  `PF_OutFlag2_FLOAT_COLOR_AWARE`, which requires Smart Render
+  (`PF_OutFlag2_SUPPORTS_SMART_RENDER`).
+
+Why: without the flags, After Effects converts to a lower depth and shows a
+warning badge on the effect. With the flags but a missing code path, 16/32 bpc
+projects render garbage. Using 32767 or 65535 for white makes 16-bit output
+slightly too dark or wrap around.
+
+Write one kernel and instantiate it per depth; clamp before converting to an
+integer type:
+
+```cpp
+template <typename P, int MaxChan> struct Px;   // P = PF_Pixel8, PF_Pixel16 or PF_PixelFloat
+// 8:  MaxChan 255    16: MaxChan PF_MAX_CHAN16 (32768)    32: float, no clamp
+static inline A_u_short to16(float v) {
+    v = v < 0.f ? 0.f : (v > 1.f ? 1.f : v);
+    return (A_u_short)(v * PF_MAX_CHAN16 + 0.5f);
+}
+```
+
+In Smart Render, pick the path from the world's pixel format
+(`PF_WorldSuite2::PF_GetPixelFormat`: `ARGB32`, `ARGB64`, `ARGB128`) and use
+the matching iterate suite (`Iterate8Suite`, `Iterate16Suite`,
+`IterateFloatSuite`). Pixel order is ARGB in After Effects.
+
+### 9. Never assume the size, origin or stride of a buffer
+
+- Use `rowbytes` to step between rows; it is not `width * sizeof(pixel)`.
+- Scale distances that come from the user in pixels by
+  `in_data->downsample_x` / `downsample_y` (a half-resolution preview has half
+  the pixels).
+- Process only the area you are asked for (`extent_hint`, or the Smart
+  Render request rects) and use the buffer's own width, height and origin.
+- Pixel aspect ratio may not be 1 ([sdk/pixel-aspect-ratio.md](sdk/pixel-aspect-ratio.md)).
+
+Why: hard-coded coordinates or `width * 4` work at full resolution in one test
+comp and break at half resolution, on cropped layers and with other effects
+upstream.
+
+```cpp
+float radius_px = (float)(radius * in_data->downsample_x.num / in_data->downsample_x.den);
+PF_Pixel8 *row = (PF_Pixel8 *)((char *)world->data + y * world->rowbytes);
+```
+
+To draw outside the layer (glows, shadows), expand the output properly: in
+Smart Render return a larger `result_rect` / `max_result_rect` from PreRender;
+without Smart Render set `PF_OutFlag_I_EXPAND_BUFFER` and give the new output
+width, height and origin in `PF_Cmd_FRAME_SETUP`. Point parameters then
+arrive shifted by the origin; see
+[sdk/pf-indata.md](sdk/pf-indata.md#point-controls-and-buffer-expansion).
+
+## Smart Render
+
+### 10. Smart Render is all or nothing
+
+With `PF_OutFlag2_SUPPORTS_SMART_RENDER`, handle both `PF_Cmd_SMART_PRE_RENDER`
+and `PF_Cmd_SMART_RENDER`:
+
+- PreRender: check out the input layer with a render request
+  (`checkout_layer`), and return the union of the result rects.
+- SmartRender: use the checked-out input world
+  (`checkout_layer_pixels`) and output (`checkout_output`), never
+  `params[0]->u.ld`. Check out every parameter you read with
+  `PF_CHECKOUT_PARAM` and check every one back in with `PF_CHECKIN_PARAM`,
+  also on error paths.
+- Keep `PF_Cmd_RENDER` working too: Premiere Pro never sends the Smart Render
+  selectors.
+
+Why: setting the flag without both selectors gives errors when the effect is
+applied. Reading `params[0]` in SmartRender, or unbalanced checkouts, gives
+"bad parameter passed to effect callback" errors.
+
+```cpp
+PF_ParamDef radius;
+AEFX_CLR_STRUCT(radius);
+ERR(PF_CHECKOUT_PARAM(in_data, GLOW_RADIUS, in_data->current_time,
+                      in_data->time_step, in_data->time_scale, &radius));
+/* ... render ... */
+ERR2(PF_CHECKIN_PARAM(in_data, &radius));   // always, even if err is set
+```
+
+## Multi-frame rendering and threads
+
+### 11. Only claim thread safety you have
+
+Set `PF_OutFlag2_SUPPORTS_THREADED_RENDERING` (After Effects 2022+) only when
+all of these hold:
+
+- No global or static variable is written after GlobalSetup (constant tables
+  built once in GlobalSetup are fine).
+- `in_data->global_data` is written only in `PF_Cmd_GLOBAL_SETUP` and
+  `PF_Cmd_GLOBAL_SETDOWN`.
+- `sequence_data` is never written at render time or in
+  `PF_Cmd_UPDATE_PARAMS_UI`; it is read at render time through
+  `PF_EffectSequenceDataSuite1` (`PF_GetConstSequenceData`).
+- No lock (mutex, gate) is held while calling back into After Effects (any
+  suite call, any checkout).
+- Rendering is deterministic: no `rand()`, no time-of-day, no state carried
+  from the previous frame. Seed noise from parameters, time and position.
+
+`PF_Cmd_SEQUENCE_SETUP`, `SEQUENCE_RESETUP`, `SEQUENCE_SETDOWN`,
+`SMART_PRE_RENDER`, `RENDER` and `SMART_RENDER` can run on several threads at
+once, at the same time as UI selectors.
+
+Why: without the flag, After Effects renders the effect one frame at a time
+and shows a "not optimised for multi-frame rendering" warning. With the flag
+but shared state, frames render differently, flicker, or crash, only on busy
+machines. Non-deterministic renders also break the frame cache.
+
+```cpp
+// wrong: one instance's value leaks into another instance's render
+static float g_radius;
+// right: read parameters in the render call (or pass them via pre_render_data)
+```
+
+If an effect must cache expensive work across frames, use the Compute Cache
+([sdk/compute-cache-api.md](sdk/compute-cache-api.md)), not sequence data.
+
+### 12. Never block a render or UI thread
+
+No network, file I/O, dialogs, sleeps or long waits inside render selectors
+or `PF_Cmd_UPDATE_PARAMS_UI`. Load files and tables once (GlobalSetup or
+SequenceSetup). Licence and update work runs in the AfterPresets native
+runtime off the render thread; render code only reads its cached state
+with `ap_is_unlocked(rt)` (lock-free, safe on any thread, never waits).
+
+Why: a render that waits on the network freezes previews for every user who
+is offline or slow, and can deadlock with multi-frame rendering.
+
+## Sequence data
+
+### 13. Flatten sequence data, and say so
+
+Sequence data is saved in the project. If it contains pointers or handles,
+flatten it: set `PF_OutFlag_SEQUENCE_DATA_NEEDS_FLATTENING` and
+`PF_OutFlag2_SUPPORTS_GET_FLATTENED_SEQUENCE_DATA`, handle
+`PF_Cmd_SEQUENCE_FLATTEN`, `PF_Cmd_SEQUENCE_RESETUP` and
+`PF_Cmd_GET_FLATTENED_SEQUENCE_DATA`. Put a version number and a
+flat/unflat marker at the same offset in both layouts, and write numbers in
+one fixed byte order. Resize the handle only in the selectors listed in
+[sdk/global-sequence-frame-data.md](sdk/global-sequence-frame-data.md#resizing-sequence-data).
+
+Why: pointers saved in a project are garbage when it reopens, on the other
+OS, or in the other app. Without the version field, an update cannot read
+projects saved by the previous version.
+
+```cpp
+typedef struct { A_u_long version; A_Boolean flat; char message[256]; PF_FpLong amount; } SeqFlat;
+```
+
+Prefer parameters (including hidden ones) over sequence data: they are saved,
+keyframable and thread-safe without extra work.
+
+## Memory and errors
+
+### 14. Allocate through After Effects and free what you allocate
+
+Large buffers come from After Effects: `PF_HandleSuite1` for memory,
+`PF_WorldSuite2` (`PF_NewWorld` / `PF_DisposeWorld`) for image buffers. Free
+every world you create with `PF_DisposeWorld` (or `PF_DISPOSE_WORLD`).
+`AEFX_CLR_STRUCT` only zeroes a struct; it frees nothing.
+
+Why: After Effects frees its caches when your allocations need memory; plain
+`malloc` competes with it and causes swapping or crashes during RAM preview.
+A world disposed with `AEFX_CLR_STRUCT` leaks a full frame every render.
+
+### 15. Return every error, never throw out of the entry point
+
+Return a `PF_Err` from every call and pass on any error a callback returns,
+including `PF_Interrupt_CANCEL` (stop the frame) and `PF_Err_OUT_OF_MEMORY`.
+Use the SDK's `ERR()` / `ERR2()` macros. Catch every C++ exception inside the
+entry point and turn it into an error. To show a message, set
+`PF_OutFlag_DISPLAY_ERROR_MESSAGE` and `out_data->return_msg`.
+
+Why: a swallowed cancel caches a half-rendered frame; an exception that
+crosses into After Effects crashes it (and behaves differently on Apple
+silicon, see [sdk/apple-silicon-support.md](sdk/apple-silicon-support.md)).
+
+```cpp
+extern "C" DllExport PF_Err EffectMain(PF_Cmd cmd, PF_InData *in_data, PF_OutData *out_data,
+                                       PF_ParamDef *params[], PF_LayerDef *output, void *extra) {
+    PF_Err err = PF_Err_NONE;
+    try {
+        switch (cmd) { /* ... */ }
+    } catch (const std::bad_alloc &) {
+        err = PF_Err_OUT_OF_MEMORY;
+    } catch (...) {
+        err = PF_Err_INTERNAL_STRUCT_DAMAGED;
+    }
+    return err;
+}
+```
+
+## Hosts and builds
+
+### 16. Premiere Pro is a different host
+
+The same binary loads in Premiere Pro from the shared MediaCore folder.
+Check `in_data->appl_id` (`'PrMr'` is Premiere Pro). Premiere never sends
+Smart Render selectors, uses other pixel formats (BGRA/VUYA, declared through
+`PF_PixelFormatSuite1`) and lacks some suites. Until Premiere support is in
+scope, test only in After Effects and say so. See
+[sdk/ppro.md](sdk/ppro.md).
+
+### 17. Build clean
+
+Compile without warnings and keep warnings on. Fix narrowing casts (they are
+the source of wrap-around colours) instead of hiding them. Debug and release
+builds use the same include paths, defines and struct alignment.
+
+## AfterPresets rules
+
+### 18. Licensing, logs and secrets
+
+- Licensing and updates come only from the AfterPresets native runtime. Do
+  not write your own licence checks, serials or network calls.
+- Never log or print licence tokens, proofs, account data or file paths that
+  contain the user's name.
+- Do not put Adobe SDK files or SDK guide text in the product, its listing or
+  a public repository.
+
+## Things tutorials get wrong
+
+Common in video tutorials and old samples. Do not copy:
+
+| Tutorial habit | Do instead |
+|---|---|
+| White in 16 bpc is 32767 (or 65535) | `PF_MAX_CHAN16` = 32768 |
+| "Free" a world with `AEFX_CLEAR_STRUCT` | `PF_DisposeWorld` (rule 14) |
+| Pass values between calls in global variables | Read parameters per render, `pre_render_data`, sequence data (rule 11) |
+| `rand()` per frame | Seed from parameters, time and position (rule 11) |
+| Read a file (LUT) inside render | Load once in GlobalSetup / SequenceSetup (rule 12) |
+| Hard-coded pixel coordinates | Downsample factors and buffer extents (rule 9) |
+| `PF_ADD_POINT` default in pixels (1920, 1080) | Percent of the layer (50, 50 = centre) (rule 7) |
+| "Treat warnings as errors: No" | Fix the casts (rule 17) |
+| Read a param through the wrong union member | Rule 7 table |
+| `xcrun altool` to notarise | Retired by Apple; `xcrun notarytool` |
+| Paste out_flags hex from the debugger into the PiPL by hand | One source for both (rule 2) |
+| "Nothing changed" after a rebuild | Stale frame cache: purge caches before judging a render ([testing.md](testing.md)) |
+| Build into Program Files with an admin IDE | Build into the project; install with a separate step |

package/runtime/docs/native/testing.md

@@ -0,0 +1,154 @@
+---
+title: Testing a native effect
+description: How the agent tests every change itself in After Effects - build, apply the effect with host_eval, render frames with comp_capture and look at them - plus the checks to run before saying done.
+---
+
+# Testing a native effect
+
+You test your own work. A change is done only when you have built it, applied
+the effect in After Effects, rendered frames, **looked at them**, and shown
+them to the user. "It compiles" is not done.
+
+The tools are on the AfterPresets MCP server:
+
+| Tool | Use |
+|---|---|
+| `host_bridge` | Status, install or removal of the dev bridge that lets the tools reach After Effects when the project has no panel |
+| `host_scratch_project` | Switch After Effects to a scratch project before changing anything |
+| `host_eval` | Run ExtendScript in After Effects: build a test comp, apply the effect, set parameters, read values |
+| `comp_capture` | Render frames of a comp at full quality and return them as images (up to 12 per call) |
+
+## One-time setup
+
+1. The first `ap dev` installs the dev bridge. Call `host_bridge` with no
+   action; if the bridge is not installed, call it with `action: "install"`.
+   Then ask the user to save their work and restart After Effects once. Afterwards `host_bridge` must report the bridge as
+   loaded in After Effects.
+2. Never quit or restart After Effects yourself while the user may have
+   unsaved work. Ask them.
+
+## Every change
+
+1. **Build and install.** Save; `ap dev` (or `dev_start`) rebuilds, signs
+   the plugin for local use and installs it into
+   `/Library/Application Support/Adobe/Common/Plug-ins/7.0/MediaCore/AfterPresets Dev/<bundleId>/`.
+   Call `dev_status` until the build is ok; fix compiler errors from its
+   `file:line` list. After Effects loads plugins only when it starts, so when
+   `dev_status` says **RESTART NEEDED**: `ap dev` restarts After Effects by
+   itself only when that is safe (a saved or scratch project, no dialog
+   open); otherwise ask the user to save their work and restart it. Never
+   quit, kill or restart After Effects yourself.
+2. **Scratch project.** Call `host_scratch_project` before you add, change or
+   delete anything in After Effects. Never test in the user's project.
+3. **Apply the effect by match name** in a test comp with `host_eval`:
+
+   ```js
+   var c = app.project.items.addComp("AP Test", 1920, 1080, 1, 4, 30);
+   var bg = c.layers.addSolid([0.15, 0.3, 0.6], "Base", 1920, 1080, 1, 4);
+   var t = c.layers.addText("Hello");                     // something with edges and alpha
+   t.property("ADBE Transform Group").property("ADBE Scale").setValue([400, 400]);
+   var fx = t.property("ADBE Effect Parade").addProperty("ACME Soft Glow");  // your match name
+   if (!fx) return "not applied";
+   fx.property(1).setValue(40);                          // first parameter after the layer
+   c.openInViewer();
+   return fx.name + " | " + fx.numProperties + " properties";
+   ```
+
+   If `addProperty` throws or returns null, the match name is wrong or After
+   Effects did not load the plugin: see [debugging.md](debugging.md).
+4. **Render and look.** Call `comp_capture` (for example `frames: [0, 60, 119]`,
+   or `seconds: [1.5]`). It clears After Effects' caches first by default, so
+   every frame comes from the build that is loaded now (undo history is kept).
+   Open each image and check what the change
+   was meant to do, plus edges, transparency and colour.
+5. **Show the user** the frames and say what you checked and what you did not.
+
+## Testing the locked (signed-out) state
+
+Dev builds from `ap dev` render **without** the licence watermark, so you
+can judge the look. To test what a signed-out buyer sees, create the file
+`~/.afterpresets/native-dev-enforce-license` (or start After Effects with
+`AP_DEV_ENFORCE_LICENSE=1`), restart After Effects (ask the user), and
+capture frames. Delete the file afterwards. Release builds always enforce
+the licence. The status button (`params[AP_PARAM_LICENSE]`, caption
+"License...") shows the state in its name, e.g. "License: sign in"; read it
+with `host_eval` if needed.
+
+## Before saying done
+
+Run what applies to the change. Each line names the classic bug it catches
+(the rules are in [rules.md](rules.md)).
+
+| Check | How | Catches |
+|---|---|---|
+| Every parameter | Set each to its minimum, default and maximum; capture | Wrong union member, ranges, division by zero |
+| Animation | Keyframe a parameter (`setValueAtTime`), capture several frames | Values read at the wrong time, cached state |
+| 16 and 32 bpc | `app.project.bitsPerChannel = 16` then `32`, capture the same frames; compare with 8 | Missing depth paths, 32767/65535 white, clamped overbrights |
+| Half resolution | `c.resolutionFactor = [2, 2]`, capture; the result must look like a smaller copy of full resolution | Ignored downsample factors |
+| Small or moved layer | Layer smaller than the comp, partly outside it | Hard-coded sizes, `rowbytes`, origin |
+| Upstream expansion | Put a Gaussian Blur before your effect, capture with the blur on and off | Buffer origin, point parameters |
+| Two instances | Apply the effect to two layers with different settings, capture | Globals and statics shared between instances |
+| Save and reopen | Save the scratch project, `app.open()` it again, capture the same frame | Parameter disk IDs, sequence data flattening |
+| Render speed | Read the render times `comp_capture` reports (caches are cleared first) | Slow paths, blocking work in render |
+
+Not covered yet (say so to the user when it matters): the Windows `.aex` is
+built on the Mac but tested by the user on a Windows PC; Premiere Pro;
+multi-frame rendering under load. For the last one, when the effect declares
+multi-frame rendering, ask the user to render the test comp from the Render
+Queue with Multi-Frame Rendering on and compare it with your captures.
+
+## Scripting pitfalls
+
+Some After Effects scripting errors abort the whole `host_eval` script, and
+`try/catch` cannot catch them. Avoid them:
+
+- **Re-fetch an effect after `moveTo()`.** `fx.moveTo(1)` invalidates `fx`;
+  the next access to the old reference aborts the script. Get it again by
+  index or name:
+
+  ```js
+  fx.moveTo(1);
+  fx = layer.property("ADBE Effect Parade").property(1);
+  ```
+
+- **Never turn an array into a string implicitly** (`"" + value`, `alert(arr)`,
+  string concatenation with a colour or point value). Use `value.join(",")`
+  or `JSON.stringify(value)`.
+- **Never open a modal dialog** from a script: no `alert`, `confirm`,
+  `prompt`, `File.openDialog`, and no `app.project.save()` without a file
+  (it shows the Save dialog). While a dialog is open After Effects answers
+  no tool calls.
+- **Save and reopen** (the "Save and reopen" check) without dialogs: save the
+  scratch project to an explicit file, open it again, then look everything
+  up again by name, because every comp, layer and effect reference from
+  before is invalid:
+
+  ```js
+  var f = new File(Folder.temp.fsName + "/ap-test-reopen.aep");
+  app.project.save(f);
+  app.open(f);
+  var c = null;
+  for (var i = 1; i <= app.project.numItems; i++) {
+      if (app.project.item(i).name === "AP Test") c = app.project.item(i);
+  }
+  var fx = c.layer("Hello").property("ADBE Effect Parade").property(1);
+  return fx.matchName;
+  ```
+
+  Then `comp_capture` the same frames as before saving and compare them.
+- **The effect's Options dialog is modal.** Never open or click it from a
+  script or tool. When it needs checking (sign-in, licence status, update
+  text), ask the user to click the effect's **Options** link or its
+  **License...** button, and to tell you or screenshot what it shows.
+
+## If something goes wrong
+
+- `comp_capture` times out or After Effects stops answering: a modal dialog
+  (error, crash report, licence) may be open. Ask the user what After Effects
+  shows; do not retry in a loop.
+- The frame did not change after a rebuild: the old binary is still loaded.
+  `dev_status` says whether a restart is needed; After Effects must restart
+  to load a new build.
+- `host_eval` or `comp_capture` returns nothing or says the script engine
+  is busy: After Effects is probably showing a dialog. Ask the user.
+- Crashes and load failures: [debugging.md](debugging.md).

package/runtime/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@afterpresets/runtime",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "private": true
 }

package/runtime/scripts/ae-sdk-docs/config.js

@@ -0,0 +1,102 @@
+"use strict";
+
+// What the generator reads and how the result is organised.
+//
+// Bumping the pin: clone the repository, check out the new commit, run
+//   node scripts/ae-sdk-docs.js --source <checkout> --out <tmp> --allow-unpinned
+// read the output, then copy the printed commit and digest here. The run fails
+// if a page or anchor named in TASKS no longer exists; fix TASKS first.
+
+const PIN = {
+  repo: "docsforadobe/after-effects-plugin-guide",
+  commit: "c3fc3fc4132bbd0088b0b32461a5f21b2a88eb7b",
+  date: "2026-11-03",
+  sdk: "After Effects 27.0 SDK",
+  digest: "sha256:246909fbbd4d9e275ef4355649e4f68039e15eeec63ae3f121fc0c4a69fa2d02",
+  site: "https://ae-plugins.docsforadobe.dev",
+};
+
+/** Source pages left out: not about effect plug-ins (3D renderers, file importers) or no use to an agent. */
+const EXCLUDE = [/^index\.md$/, /^history\.md$/, /^artisans\//, /^aeios\//];
+
+const RENAME = {
+  "effect-details/tips-tricks.md": "effect-tips",
+  "effect-ui-events/tips-and-tricks.md": "ui-tips",
+  "intro/next-steps.md": "intro-next-steps",
+};
+
+// Sections whose page names are too generic on their own ("overview",
+// "multithreading", "global-outflags").
+const PREFIX = { "ppro/": "ppro", "audio/": "audio", "aegps/": "aegp" };
+
+/** Output file name (without .md) for a source page path like "effect-basics/PF_InData.md". */
+function outputName(sourcePath) {
+  if (RENAME[sourcePath]) return RENAME[sourcePath];
+  const base = sourcePath
+    .split("/")
+    .pop()
+    .replace(/\.md$/, "")
+    .toLowerCase()
+    .replace(/_/g, "-");
+  const dir = Object.keys(PREFIX).find((d) => sourcePath.indexOf(d) === 0);
+  if (!dir) return base;
+  const stem = PREFIX[dir];
+  if (base === stem || base === stem + "s" || base.indexOf(stem + "-") === 0) return base;
+  return stem + "-" + base;
+}
+
+// Split thresholds in characters (about 4 characters per token).
+const LIMITS = { maxChars: 14000, singleMax: 18000, minChars: 4000, mergeMax: 9000 };
+
+/** Reading order for a first effect. */
+const START_HERE = [
+  "intro/what-can-i-do.md",
+  "effect-basics/entry-point.md",
+  "effect-basics/command-selectors.md#calling-sequence",
+  "effect-basics/parameters.md",
+  "smartfx/smartfx.md",
+  "effect-details/multi-frame-rendering-in-ae.md",
+];
+
+/** Task -> source references ("page.md" or "page.md#anchor"). Every reference must resolve. */
+const TASKS = [
+  ["Start a new effect: how plug-ins work, the entry point", ["intro/what-can-i-do.md", "effect-basics/effect-basics.md", "effect-basics/entry-point.md"]],
+  ["Copy from an Adobe sample project", ["intro/sample-projects.md#sample-project-descriptions"]],
+  ["Handle a command (PF_Cmd_*), know which command comes when", ["effect-basics/command-selectors.md#calling-sequence", "effect-basics/command-selectors.md#command-selectors-table"]],
+  ["Read what After Effects passes in (in_data: time, downsampling, extent_hint)", ["effect-basics/PF_InData.md#pf_indata-members", "effect-basics/PF_InData.md#extent_hint-usage"]],
+  ["Set capabilities: out_flags / out_flags2", ["effect-basics/PF_OutData.md#pf_outflags", "effect-basics/PF_OutData.md#pf_outflags2"]],
+  ["Write or change the PiPL (match name, category, version, flags)", ["intro/pipl-resources.md", "intro/pipl-resources.md#multiple-pipls"]],
+  ["Add a parameter (slider, color, point, popup, checkbox, layer...)", ["effect-basics/parameters.md#parameter-types", "effect-basics/PF_ParamDef.md#pf_paramdef-members", "effect-basics/PF_ParamDef.md#parameter-flags"]],
+  ["Add, remove or reorder parameters in an effect that has shipped", ["effect-details/changing-parameter-orders.md"]],
+  ["Show, hide, enable or change parameters from code", ["effect-details/parameter-supervision.md#updating-parameter-ui", "effect-details/parameter-supervision.md#updating-parameter-values"]],
+  ["Read a parameter at another time, or a layer parameter's pixels", ["effect-details/interaction-callback-functions.md#interaction-callbacks", "effect-details/interaction-callback-functions.md#parameter-checkout-behavior"]],
+  ["Float values for color, point and angle parameters", ["effect-details/parameters-floating-point-values.md"]],
+  ["Store custom data in a parameter (arbitrary data)", ["effect-details/arbitrary-data-parameters.md"]],
+  ["Loop over pixels (iterate 8/16/32 bpc)", ["effect-details/iteration-suites.md", "effect-basics/PF_EffectWorld.md#pf_effectworld-structure", "effect-basics/PF_EffectWorld.md#rowbytes-in-pf_effectworlds"]],
+  ["Smart Render (PreRender / SmartRender, checking out layers)", ["smartfx/smartfx.md#how-to-smartify", "smartfx/smartfx.md#pf_cmd_smart_pre_render", "smartfx/smartfx.md#pf_cmd_smart_render"]],
+  ["Support 16 bpc and 32 bpc (float) color", ["smartfx/smartfx.md#the-way-things-are-now", "effect-ui-events/tips-and-tricks.md#how-deep-are-my-pixels", "effect-basics/PF_EffectWorld.md#pf_pixelptr-accessor-macros"]],
+  ["Draw outside the layer bounds (glows, shadows: expand the output)", ["effect-basics/PF_InData.md#point-controls-and-buffer-expansion", "smartfx/smartfx.md#rectangles", "smartfx/smartfx.md#the-size-of-a-layer"]],
+  ["Multi-frame rendering and thread safety", ["effect-details/multi-frame-rendering-in-ae.md", "effect-details/multi-frame-rendering-in-ae.md#what-does-it-mean-for-an-effect-to-be-thread-safe", "effect-details/accessing-function-suites.md#threading"]],
+  ["Cache expensive results across frames and threads (Compute Cache)", ["effect-details/compute-cache-api.md"]],
+  ["Global, sequence and frame data (and flattening)", ["effect-details/global-sequence-frame-data.md", "effect-details/multi-frame-rendering-in-ae.md#sequence-data-in-multi-frame-rendering"]],
+  ["Allocate memory and image buffers", ["effect-details/memory-allocation.md", "effect-details/image-buffer-management-functions.md"]],
+  ["Use a function suite (AcquireSuite, versions)", ["effect-details/accessing-function-suites.md", "intro/compatibility-across-multiple-versions.md#api-versions"]],
+  ["Sample, transform, blend, fill and convert color (utility callbacks)", ["effect-details/graphics-utility-suites.md", "effect-details/color-space-conversion.md", "effect-details/useful-utility-functions.md"]],
+  ["Non-square pixels and downsampled previews", ["effect-details/pixel-aspect-ratio.md"]],
+  ["Masks and paths, cameras and lights, motion blur", ["effect-details/working-with-paths.md", "effect-details/accessing-camera-light-information.md", "effect-details/motion-blur.md"]],
+  ["Custom UI in the comp or Effect Controls (events, Drawbot)", ["effect-ui-events/effect-ui-events.md", "effect-ui-events/custom-ui-and-drawbot.md", "effect-ui-events/PF_EventExtra.md", "effect-ui-events/ui-callbacks.md"]],
+  ["GPU rendering (Metal, CUDA, OpenCL, DirectX)", ["intro/gpu-build-instructions.md"]],
+  ["Call AEGP suites from an effect (project, layers, streams)", ["aegps/cheating-effect-usage-of-aegp-suites.md", "aegps/aegp-suites.md", "aegps/aegp-details.md#accessing-pixels-from-effect-layer-parameters"]],
+  ["Report errors, handle exceptions, out-of-memory", ["effect-basics/errors.md", "intro/exceptions.md"]],
+  ["Debug a plug-in (attach a debugger, reset preferences)", ["intro/debugging-plug-ins.md", "intro/debugging-ae-macos.md"]],
+  ["Build for Apple silicon (universal) and Windows on Arm, export only the entry point", ["intro/apple-silicon-support.md", "intro/windows-on-arm-support.md", "intro/symbol-export.md"]],
+  ["Where the plug-in is installed", ["intro/where-installers-should-put-plug-ins.md", "ppro/plug-in-installation.md"]],
+  ["Support older After Effects versions, see what changed in each SDK", ["intro/compatibility-across-multiple-versions.md", "intro/whats-new.md"]],
+  ["Effects panel: search keywords, description and preview media", ["intro/pipl-resources.md#search-keywords-and-description", "effect-details/effect-preview-media.md"]],
+  ["Localized names and UTF-8 strings", ["intro/localization.md"]],
+  ["Make the effect work in Premiere Pro", ["ppro/ppro.md", "ppro/basic-host-differences.md", "ppro/bigger-differences.md", "ppro/multithreading.md", "ppro/unsupported-features.md"]],
+  ["Audio effects", ["audio/audio.md", "audio/accessing-audio-data.md"]],
+  ["Performance, caching and testing tips from Adobe", ["effect-details/tips-tricks.md", "effect-details/tips-tricks.md#testing", "effect-ui-events/tips-and-tricks.md#ui-performance"]],
+];
+
+module.exports = { PIN, EXCLUDE, RENAME, PREFIX, LIMITS, START_HERE, TASKS, outputName };