afterpresets 0.2.0 → 0.4.0

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 ap host eval, render frames with ap 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 commands (run them from the project folder as `npx ap ...`):
+
+| Command | Use |
+|---|---|
+| `ap host bridge` | Status, install or removal of the dev bridge that lets these commands reach After Effects when the project has no panel |
+| `ap host scratch` | Switch After Effects to a scratch project before changing anything |
+| `ap host eval` | Run ExtendScript in After Effects: build a test comp, apply the effect, set parameters, read values |
+| `ap comp capture` | Render frames of a comp at full quality and save them as PNG files (up to 12 per run) |
+
+## One-time setup
+
+1. The first `ap dev` installs the dev bridge. Run `ap host bridge`; if
+   the bridge is not installed, run `ap host bridge install`.
+   Then ask the user to save their work and restart After Effects once. Afterwards `ap 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 `ap dev --background`) rebuilds, signs
+   the plugin for local use and installs it into
+   `/Library/Application Support/Adobe/Common/Plug-ins/7.0/MediaCore/AfterPresets Dev/<bundleId>/`.
+   Run `ap 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
+   `ap 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.** Run `ap host scratch` 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 `ap 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.** Run `ap 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 `ap 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 `ap 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 `ap 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 commands.
+- **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 `ap 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
+
+- `ap 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.
+  `ap dev status` says whether a restart is needed; After Effects must restart
+  to load a new build.
+- `ap host eval` or `ap 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.4.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 };