afterpresets 0.2.0 → 0.4.0

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

@@ -23,8 +23,8 @@ try {
 }
 ```
 
-The MCP `host_eval` tool already wraps each call in an undo group named
-"AfterPresets MCP".
+`ap host eval` already wraps each call in an undo group named
+"AfterPresets agent".
 
 ## The active composition
 
@@ -54,4 +54,4 @@ APIs and return `{ ok: false, message }` when they are missing.
 
 `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.
+with `ap host eval` before changing working code.

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

@@ -14,8 +14,8 @@ makes sense in Premiere Pro in `jsx/ppro/`.
 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.
+and tell the user how many undo steps an action adds. `ap host eval`
+cannot group them either.
 
 ## The active sequence
 
@@ -68,7 +68,7 @@ Frame-accurate maths: convert with the sequence's timebase
 
 - `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
+- Save with `app.project.save()`. `ap host scratch` creates a
   new project in the temp folder and leaves the user's project open.
 
 ## Versions
@@ -81,4 +81,4 @@ return `{ ok: false, message }` when they are missing.
 
 `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.
+likely mistakes. Hints can be wrong; confirm with `ap host eval`.

package/runtime/docs/cep/host.md

@@ -33,6 +33,14 @@ An extension for both apps can define the same function in `jsx/aeft/` and
 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),
@@ -123,6 +131,6 @@ 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 (the MCP `host_scratch_project` tool) for
-anything that changes the project. With the MCP tools, `host_eval` runs in the
+state. Use a disposable project (`ap host scratch`) for
+anything that changes the project. `ap host eval` runs in the
 app that runs the connected panel.

package/runtime/docs/common/README.md

@@ -17,7 +17,7 @@ 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 ExtendScript functions in the app (After Effects or Premiere Pro).
 - `AP.panels` and `AP.events` for extensions with more than one panel.

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 `ap host eval`, frames from
+`ap 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 (`ap comp capture` clears caches by
+  default; keep it that way).
+
+## Slow renders
+
+`ap 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.

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 |