afterpresets 0.1.0 → 0.3.0

package/template/native/docs/initial_setup.md

@@ -0,0 +1,179 @@
+# Initial setup
+
+Do this once per computer. The user is usually not a programmer and may not
+have a terminal open (for example, they use the Code tab of the Claude
+desktop app). **Run every command yourself**; ask the user only for the
+steps marked **User**, one at a time, in plain words, and wait for "Done".
+Never ask them to type a command, and never use `sudo` yourself. If a
+command fails because your sandbox blocks the internet or writing to
+`~/.afterpresets`, ask the user to allow it to run outside the sandbox; do
+not work around it.
+
+Follow the steps for this computer's system (macOS or Windows). A Mac builds
+the macOS version and cross-compiles the Windows version; a Windows PC builds
+the Windows version only.
+
+## 1. Tools
+
+- [ ] `node --version` prints 20 or newer. If Node is missing: on Windows run
+  `winget install -e --id OpenJS.NodeJS.LTS`; on a Mac, **User** installs
+  the "LTS" version from https://nodejs.org (a normal installer). Then check
+  again (a new chat may be needed for the agent to see it).
+- [ ] `npm install` has run; `node_modules/afterpresets` exists.
+
+**macOS:**
+
+- [ ] Homebrew: `brew --version` works (also try `/opt/homebrew/bin/brew`
+  and `/usr/local/bin/brew`). If not, **User**: "Open https://brew.sh, copy
+  the install line into the Terminal app, press Return, and type your Mac
+  password when asked (nothing shows while you type). Press Return again
+  when it asks. If Apple's Command Line Tools are missing it downloads them
+  too (about 1 GB from Apple, 5-15 minutes); wait until it says
+  'Installation successful'." Then check again (Homebrew prints two lines to
+  add it to the PATH; follow them).
+- [ ] Apple's Command Line Tools (Apple's compiler and signing tools; Xcode
+  itself is not needed): `xcode-select -p` prints a folder. Homebrew's
+  installer normally installed them. If not, run `xcode-select --install`
+  and tell the **User**: "A macOS window asks to install the Command Line
+  Tools: click **Install** and wait until it finishes (about 5-15 minutes,
+  it downloads about 1 GB from Apple)."
+- [ ] Build tools: `brew install cmake ninja zig` (you run it). `cmake
+  --version`, `ninja --version` and `zig version` all work afterwards.
+
+**Windows** (Visual Studio is not needed):
+
+- [ ] Build tools, with winget (you run them; no administrator needed):
+  `winget install -e --id Kitware.CMake`, `winget install -e --id
+  Ninja-build.Ninja`, `winget install -e --id zig.zig`. `cmake --version`,
+  `ninja --version` and `zig version` all work afterwards (a new terminal,
+  or a new chat, may be needed to see them).
+
+**Both:**
+
+- [ ] The account: `whoami` (MCP) or `npx ap whoami`. If it says "not logged
+  in", call `login` (MCP) or run `npx ap login` in the background, then tell
+  the **User**: "Your browser opened an AfterPresets page; click **Authorize
+  CLI**." Wait with `login_status`, or until the command finishes.
+
+## 2. Adobe's After Effects SDK (one time per computer)
+
+Adobe does not allow AfterPresets to ship its SDK, and downloading it needs
+the user's Adobe ID, so this step is theirs.
+
+- [ ] Run `npx ap sdk`. If it says the SDK is installed, go on.
+- [ ] Otherwise run `npx ap sdk install`. It opens Adobe's download page. Tell
+  the **User**: "Sign in with your Adobe ID on the page that opened, and
+  download the **After Effects** SDK for **macOS** (or **Windows** on a PC; a
+  zip). Tell me when it
+  is in your Downloads folder." Never ask for their Adobe password.
+- [ ] Run `npx ap sdk install` again: it finds the zip in Downloads, checks
+  it and installs it into `~/.afterpresets/sdk/` (Windows:
+  `%USERPROFILE%\.afterpresets\sdk\`). If the zip is elsewhere,
+  pass its path: `npx ap sdk install <path to zip>`.
+
+## 3. AfterPresets MCP
+
+The `afterpresets` MCP server (`ap mcp`) gives you the CLI (login, check,
+dev, build, push), the docs, and After Effects itself (`host_eval`,
+`host_scratch_project`, `comp_capture`).
+
+- **Claude (desktop app Code tab, or Claude Code):** `.mcp.json` declares it.
+  If its tools are missing because this project was just created in this
+  chat (or in another folder), tell the **User** exactly how to start a new
+  chat in this folder, with its full path, and to approve the AfterPresets
+  tools when Claude asks:
+  - Claude app: "In the **Code** tab, start a new session, choose the
+    folder `<full path>`, and approve the AfterPresets tools when asked."
+  - Claude Code in a terminal: "Type `/exit`, then run
+    `cd "<full path>" && claude`, and approve the AfterPresets tools."
+  - Cursor or VS Code: "**File → Open Folder…**, choose `<full path>`,
+    open a new chat, and enable the afterpresets MCP server if asked."
+  Give them the message to paste into the new chat: "Continue the
+  AfterPresets setup: follow docs/initial_setup.md step by step until you
+  have shown me the starter effect rendering in After Effects, then ask me
+  what to build." Stop there; the
+  new chat continues from this file.
+- **Codex CLI** (run in this folder):
+
+  ```sh
+  codex mcp add afterpresets -- node node_modules/afterpresets/bin/ap.js mcp
+  ```
+
+  Then tell the **User**: "Quit Codex and start it again in this folder:
+  `cd "<full path>" && codex`."
+
+- **Other agents:** add a stdio server that runs
+  `node node_modules/afterpresets/bin/ap.js mcp` in this folder.
+
+- [ ] The `afterpresets` tools are visible to you.
+
+## 4. First build
+
+- [ ] Call `dev_start` (or `npx ap dev` if the user runs it). It builds the
+  effect, installs it into After Effects' dev plugin folder
+  (macOS: `/Library/Application Support/Adobe/Common/Plug-ins/7.0/MediaCore/AfterPresets Dev/`;
+  Windows: `C:\Program Files\Adobe\Common\Plug-ins\7.0\MediaCore\AfterPresets Dev\`),
+  installs the AfterPresets dev bridge (how the tools reach After Effects),
+  and converts Adobe's SDK guide into `docs/afterpresets/sdk/`. Then
+  `dev_status` until the build is done.
+- [ ] If it says the dev plugin folder needs an administrator, that is a
+  **User** step, needed once. **macOS:** it gives one Terminal line (`sudo mkdir -p …
+  && sudo chown …`). Tell the **User**: "Open the Terminal app, paste this
+  line, press Return and type your Mac password (nothing shows while you
+  type)." and give them the exact line it printed. (When `ap dev` runs in an
+  interactive terminal it may show the macOS administrator window instead:
+  then the **User** just enters their password there.) Never run `sudo`
+  yourself. **Windows:** it gives one PowerShell line (`New-Item … ;
+  icacls …`). Tell the **User**: "Right-click **Start**, choose **Terminal
+  (Admin)** or **Windows PowerShell (Admin)**, click **Yes**, paste this
+  line, press Enter, and tell me Done." and give them the exact line it
+  printed. Never elevate yourself. Then run `dev_start` / `dev_status`
+  again; later builds install without an administrator.
+- [ ] If it reports compiler errors on the untouched starter, the SDK or a
+  build tool is wrong: re-check steps 1 and 2 and read the hint it prints.
+- [ ] `docs/afterpresets/sdk/README.md` exists. If it says the guide could
+  not be downloaded, check the internet connection and run `npx ap docs`.
+
+## 5. Restart After Effects once
+
+- [ ] **User:** "Save your work in After Effects, then quit and reopen it."
+  (Needed now because After Effects loads plugins and the dev bridge only
+  when it starts. Later, on a Mac, `ap dev` restarts it for you when that
+  is safe, or tells you to ask; on Windows always ask the user.)
+- [ ] `host_bridge` (no action) says the bridge is loaded in After Effects.
+
+## 6. Prove the loop
+
+- [ ] A harmless host call works: `host_eval` with `app.version`.
+- [ ] The starter effect is loaded: in `host_eval`, look for the
+  `matchName` from `effect.json` in `app.effects` (see
+  `docs/afterpresets/debugging.md`).
+- [ ] `host_scratch_project`, then apply the starter effect to a solid in a
+  test comp with `host_eval` and capture two frames with `comp_capture`
+  (`docs/afterpresets/testing.md`). Look at them: the effect is visible.
+- [ ] Show the **User** the frames: "This is the starter effect, running in
+  After Effects. Next, tell me what yours should do."
+
+## 7. Ask what to build
+
+Only now, with the starter effect rendering, ask what the effect should do.
+Do not start building from a vague idea.
+
+- [ ] Ask the **User** to describe the look in detail, in their own words.
+  Invite references: images or video frames of the look they want, another
+  effect they like, or a frame from their own project. They can drag images
+  into the chat.
+- [ ] Ask short questions about anything unclear, a few at a time (for
+  example: which controls they want, what each one changes, how it should
+  animate, whether it works on the layer's edges or its whole image).
+- [ ] Repeat back a short plan in plain words (the look, the controls and
+  their ranges) and wait for their OK.
+- [ ] Write the Overview in `AGENTS.md` from the plan, following the
+  instructions there. Keep it current from now on.
+- [ ] Turn the starter into the product: its name, category, controls and
+  render code (`docs/code_guide.md` lists what to keep). Build it in small
+  steps, rendering and showing frames after each one.
+
+Repeat after moving the project, installing a new After Effects version, or
+switching agents (skip step 7 when the Overview in `AGENTS.md` is already
+written).

package/template/native/docs/release_checklist.md

@@ -0,0 +1,24 @@
+# Before the first production release
+
+Do this once, before the first `push` to `production`. Tell the user what you
+are doing; show them the frames and wait for their feedback.
+
+- [ ] **Licensing matches the price.** A paid product keeps
+  `"license": true` in `effect.json` (`ap check` and `ap push` refuse
+  otherwise). A free one may remove it. See `docs/code_guide.md`.
+- [ ] **The locked state works.** Turn enforcement on as described in
+  "Testing the locked (signed-out) state" in `docs/afterpresets/testing.md`,
+  restart After Effects, and render frames signed out: the effect must still
+  render (with the watermark), never crash or hang. Render frames signed in
+  too. Then turn enforcement off again.
+- [ ] **Show the user** the locked and unlocked frames and ask for feedback.
+- [ ] **The match name and control ids are final.** After this release they
+  can never change (see `docs/code_guide.md`). Confirm the effect's name and
+  controls with the user.
+- [ ] **A test release works.** `push` to `test` and let the user try it.
+  Built on a Mac, the release also has the Windows version: tell the user to
+  test it on a Windows PC before selling it there.
+- [ ] `check` passes with no errors.
+
+Then `push` to `production`: show the user the summary it returns, and call
+it again with its `confirmToken` only after they approve.

package/template/native/effect.json

@@ -0,0 +1,16 @@
+{
+  "name": "__EFFECT_NAME__",
+  "matchName": "__MATCH_NAME__",
+  "category": "AfterPresets",
+  "description": "Tints the layer toward a colour.",
+  "license": true,
+  "updates": "background",
+  "params": [
+    { "key": "amount", "id": 1, "type": "slider", "name": "Amount", "min": 0, "max": 100, "default": 50, "precision": 1, "display": "percent" },
+    { "key": "color", "id": 2, "type": "color", "name": "Color", "default": "#FF4000" },
+    { "key": "mode", "id": 3, "type": "popup", "name": "Mode", "choices": ["Tint", "Screen", "Multiply"], "default": "Tint" },
+    { "key": "gradient", "id": 4, "type": "checkbox", "name": "Gradient", "label": "Fade across layer", "default": false },
+    { "key": "center", "id": 5, "type": "point", "name": "Gradient Center", "default": [50, 50] },
+    { "key": "angle", "id": 6, "type": "angle", "name": "Gradient Angle", "default": 90 }
+  ]
+}

package/template/native/gitignore

@@ -0,0 +1,8 @@
+# Build output (ap build / ap dev)
+/build/
+/dist/
+
+# Never commit Adobe's SDK (it lives in ~/.afterpresets/sdk/)
+AfterEffectsSDK*/
+
+.DS_Store

package/template/native/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "__SLUG__",
+  "private": true,
+  "scripts": {
+    "dev": "ap dev",
+    "check": "ap check",
+    "build": "ap build",
+    "push": "ap push",
+    "docs": "ap docs"
+  },
+  "devDependencies": {
+    "afterpresets": "^__CLI_VERSION__"
+  }
+}

package/template/native/src/Effect.cpp

@@ -0,0 +1,224 @@
+// The starter effect: tints the layer toward a colour (Tint, Screen or
+// Multiply), optionally fading across the layer along a gradient.
+//
+// Plain After Effects SDK code. Names, flags, version and parameters come from
+// effect.json through the generated ap_effect_config.h / ap_effect_params.h:
+// change effect.json, not the numbers here.
+//
+//   8/16/32 bpc        DEEP_COLOR_AWARE + FLOAT_COLOR_AWARE, one template (Render.h)
+//   Smart Render       PF_Cmd_SMART_PRE_RENDER / PF_Cmd_SMART_RENDER
+//   Multi-frame render no mutable globals; everything a render needs is on the stack
+//   AfterPresets       status button + Options dialog (License.cpp, ap_native)
+#include "AEConfig.h"
+#include "entry.h"
+#include "AE_Effect.h"
+#include "AE_EffectVers.h"
+#include "AE_EffectCB.h"
+#include "AE_EffectCBSuites.h"
+#include "AE_EffectSuites.h"
+#include "AE_Macros.h"
+#include "Param_Utils.h"
+
+#include <cmath>
+#include <cstdio>
+#include <cstring>
+#include <new>
+
+#include "ap_effect_params.h" // generated from effect.json
+#include "License.h"
+#include "Render.h"
+
+namespace {
+
+// Decided once per frame in PreRender and handed to SmartRender.
+struct PreRenderData {
+  A_long left, top; // where the output buffer sits in layer space (downsampled pixels)
+  A_long unlocked;  // license state for this frame (also mixed into the cache key)
+};
+
+void delete_pre_render_data(void *data) { delete static_cast<PreRenderData *>(data); }
+
+PF_Err about(PF_OutData *out_data) {
+  std::snprintf(out_data->return_msg, sizeof out_data->return_msg, "%s %s\r%s", AP_EFFECT_NAME, AP_VERSION,
+                AP_DESCRIPTION);
+  return PF_Err_NONE;
+}
+
+PF_Err global_setup(PF_OutData *out_data) {
+  out_data->my_version = AP_EFFECT_VERSION; // equals the PiPL's eVER (both from afterpresets.json)
+  out_data->out_flags = AP_OUT_FLAGS;       // equals the PiPL's eGLO (both from effect.json)
+  out_data->out_flags2 = AP_OUT_FLAGS2;     // equals the PiPL's eGL2
+  license::start();
+  return PF_Err_NONE;
+}
+
+PF_Err params_setup(PF_InData *in_data, PF_OutData *out_data) {
+  char status[32];
+  license::status_name(status, sizeof status);
+  return ap_add_params(in_data, out_data, status, license::button_label());
+}
+
+// The status button's name shows the license / update state. Names are the
+// only text an effect can change in the Effect Controls without custom UI.
+PF_Err update_params_ui(PF_InData *in_data, PF_ParamDef *params[]) {
+  PF_ParamDef def = *params[AP_PARAM_LICENSE];
+  char status[32];
+  license::status_name(status, sizeof status);
+  if (std::strncmp(def.PF_DEF_NAME, status, sizeof def.PF_DEF_NAME) == 0) return PF_Err_NONE;
+  std::snprintf(def.PF_DEF_NAME, sizeof def.PF_DEF_NAME, "%s", status);
+  const PF_ParamUtilsSuite3 *pu = nullptr;
+  PF_Err err = PF_Err_NONE;
+  if (in_data->pica_basicP->AcquireSuite(kPFParamUtilsSuite, kPFParamUtilsSuiteVersion3, (const void **)&pu) == 0 && pu) {
+    err = pu->PF_UpdateParamUI(in_data->effect_ref, AP_PARAM_LICENSE, &def);
+    in_data->pica_basicP->ReleaseSuite(kPFParamUtilsSuite, kPFParamUtilsSuiteVersion3);
+  }
+  return err;
+}
+
+// Effect > Options or the status button: the AfterPresets dialog (sign in,
+// buy, sign out, update notes). Re-render: signing in or out changes the frame.
+PF_Err show_options(PF_OutData *out_data) {
+  license::options_dialog();
+  out_data->out_flags |= PF_OutFlag_FORCE_RERENDER;
+  return PF_Err_NONE;
+}
+
+PF_Err user_changed_param(PF_OutData *out_data, const PF_UserChangedParamExtra *extra) {
+  if (extra->param_index == AP_PARAM_LICENSE) return show_options(out_data);
+  return PF_Err_NONE;
+}
+
+PF_Err pre_render(PF_InData *in_data, PF_PreRenderExtra *extra) {
+  PF_RenderRequest req = extra->input->output_request;
+  PF_CheckoutResult in_result;
+  PF_Err err = extra->cb->checkout_layer(in_data->effect_ref, AP_PARAM_INPUT, AP_PARAM_INPUT, &req,
+                                         in_data->current_time, in_data->time_step, in_data->time_scale, &in_result);
+  if (err) return err;
+  // Pixel-independent: the output covers exactly what the input provides.
+  extra->output->result_rect = in_result.result_rect;
+  extra->output->max_result_rect = in_result.max_result_rect;
+  // The license state is part of the frame: mix it into After Effects' cache key
+  // (with PF_OutFlag2_I_MIX_GUID_DEPENDENCIES) so a frame rendered locked is
+  // never shown after sign-in, and the reverse.
+  A_long unlocked = license::unlocked() ? 1 : 0;
+  err = extra->cb->GuidMixInPtr(in_data->effect_ref, sizeof unlocked, &unlocked);
+  if (err) return err;
+  PreRenderData *data = new (std::nothrow) PreRenderData{in_result.result_rect.left, in_result.result_rect.top, unlocked};
+  if (!data) return PF_Err_OUT_OF_MEMORY;
+  extra->output->pre_render_data = data;
+  extra->output->delete_pre_render_data_func = delete_pre_render_data;
+  return PF_Err_NONE;
+}
+
+PF_Err smart_render(PF_InData *in_data, PF_SmartRenderExtra *extra) {
+  PF_Err err = PF_Err_NONE;
+  PF_EffectWorld *input = nullptr, *output = nullptr;
+  err = extra->cb->checkout_layer_pixels(in_data->effect_ref, AP_PARAM_INPUT, &input);
+  if (!err) err = extra->cb->checkout_output(in_data->effect_ref, &output);
+
+  // Check out every parameter at the current time (checked back in below).
+  const int ids[] = {AP_PARAM_AMOUNT, AP_PARAM_COLOR, AP_PARAM_MODE, AP_PARAM_GRADIENT, AP_PARAM_CENTER, AP_PARAM_ANGLE};
+  const int n = (int)(sizeof ids / sizeof ids[0]);
+  PF_ParamDef p[sizeof ids / sizeof ids[0]];
+  bool checked[sizeof ids / sizeof ids[0]] = {};
+  for (int i = 0; i < n && !err; ++i) {
+    AEFX_CLR_STRUCT(p[i]);
+    err = PF_CHECKOUT_PARAM(in_data, ids[i], in_data->current_time, in_data->time_step, in_data->time_scale, &p[i]);
+    checked[i] = !err;
+  }
+
+  if (!err && input && output) {
+    const PreRenderData *pre = static_cast<const PreRenderData *>(extra->input->pre_render_data);
+    TintParams tp;
+    tp.amount = (float)(p[0].u.fs_d.value / 100.0);
+    tp.r = p[1].u.cd.value.red / 255.f;
+    tp.g = p[1].u.cd.value.green / 255.f;
+    tp.b = p[1].u.cd.value.blue / 255.f;
+    tp.mode = p[2].u.pd.value;
+    tp.gradient = p[3].u.bd.value != 0;
+    // Point values arrive in layer pixels at the current resolution (16.16
+    // fixed; After Effects already applied the downsample factor; verified at
+    // half resolution). The buffers start at the pre-render rectangle's corner.
+    tp.cx = (float)p[4].u.td.x_value / 65536.f - (pre ? pre->left : 0);
+    tp.cy = (float)p[4].u.td.y_value / 65536.f - (pre ? pre->top : 0);
+    const float rad = (float)p[5].u.ad.value / 65536.f * 3.14159265f / 180.f; // 0 degrees points up
+    tp.dirx = std::sin(rad);
+    tp.diry = -std::cos(rad);
+    tp.span = (float)(input->width > input->height ? input->width : input->height);
+    if (tp.span < 1.f) tp.span = 1.f;
+    tp.watermark = pre ? !pre->unlocked : !license::unlocked();
+
+    PF_PixelFormat fmt = PF_PixelFormat_ARGB32;
+    const PF_WorldSuite2 *ws = nullptr;
+    if (in_data->pica_basicP->AcquireSuite(kPFWorldSuite, kPFWorldSuiteVersion2, (const void **)&ws) == 0 && ws) {
+      err = ws->PF_GetPixelFormat(output, &fmt);
+      in_data->pica_basicP->ReleaseSuite(kPFWorldSuite, kPFWorldSuiteVersion2);
+    }
+    const int w = output->width < input->width ? output->width : input->width;
+    const int h = output->height < input->height ? output->height : input->height;
+    const char *src = (const char *)input->data;
+    char *dst = (char *)output->data;
+    if (!err) {
+      switch (fmt) {
+      case PF_PixelFormat_ARGB128:
+        tint_rows<PF_PixelFloat, 1, true>(src, input->rowbytes, dst, output->rowbytes, w, h, tp);
+        break;
+      case PF_PixelFormat_ARGB64:
+        tint_rows<PF_Pixel16, PF_MAX_CHAN16, false>(src, input->rowbytes, dst, output->rowbytes, w, h, tp);
+        break;
+      case PF_PixelFormat_ARGB32:
+        tint_rows<PF_Pixel8, PF_MAX_CHAN8, false>(src, input->rowbytes, dst, output->rowbytes, w, h, tp);
+        break;
+      default:
+        err = PF_Err_BAD_CALLBACK_PARAM;
+      }
+    }
+  }
+
+  for (int i = 0; i < n; ++i) {
+    if (checked[i]) {
+      PF_Err e2 = PF_CHECKIN_PARAM(in_data, &p[i]);
+      if (!err) err = e2;
+    }
+  }
+  if (input) {
+    PF_Err e2 = extra->cb->checkin_layer_pixels(in_data->effect_ref, AP_PARAM_INPUT);
+    if (!err) err = e2;
+  }
+  return err;
+}
+
+} // namespace
+
+extern "C" DllExport PF_Err PluginDataEntryFunction2(PF_PluginDataPtr inPtr, PF_PluginDataCB2 inPluginDataCallBackPtr,
+                                                     SPBasicSuite *, const char *, const char *) {
+  PF_Err result = PF_Err_INVALID_CALLBACK;
+  result = PF_REGISTER_EFFECT_EXT2(inPtr, inPluginDataCallBackPtr, AP_EFFECT_NAME, AP_MATCH_NAME, AP_CATEGORY,
+                                   AE_RESERVED_INFO, "EffectMain", AP_SUPPORT_URL);
+  return result;
+}
+
+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) {
+  (void)output;
+  PF_Err err = PF_Err_NONE;
+  try {
+    switch (cmd) {
+    case PF_Cmd_ABOUT: err = about(out_data); break;
+    case PF_Cmd_GLOBAL_SETUP: err = global_setup(out_data); break;
+    case PF_Cmd_GLOBAL_SETDOWN: license::stop(); break;
+    case PF_Cmd_PARAMS_SETUP: err = params_setup(in_data, out_data); break;
+    case PF_Cmd_UPDATE_PARAMS_UI: err = update_params_ui(in_data, params); break;
+    case PF_Cmd_USER_CHANGED_PARAM:
+      err = user_changed_param(out_data, static_cast<const PF_UserChangedParamExtra *>(extra));
+      break;
+    case PF_Cmd_DO_DIALOG: err = show_options(out_data); break;
+    case PF_Cmd_SMART_PRE_RENDER: err = pre_render(in_data, static_cast<PF_PreRenderExtra *>(extra)); break;
+    case PF_Cmd_SMART_RENDER: err = smart_render(in_data, static_cast<PF_SmartRenderExtra *>(extra)); break;
+    default: break;
+    }
+  } catch (...) {
+    err = PF_Err_INTERNAL_STRUCT_DAMAGED; // never let a C++ exception reach After Effects
+  }
+  return err;
+}

package/template/native/src/License.cpp

@@ -0,0 +1,95 @@
+#include "License.h"
+
+#include <cstdio>
+#include <cstdlib>
+#include <string>
+
+#include "ap_effect_config.h" // generated: AP_BUNDLE_ID, AP_VERSION, AP_API_BASE, AP_PUBLIC_KEY, ...
+#include "ap_native.h"
+
+namespace license {
+namespace {
+
+// Process-wide; set and cleared on the main thread only (GLOBAL_SETUP /
+// GLOBAL_SETDOWN), read-only while frames render.
+ap_runtime *g_ap = nullptr; // ap-check: allow mfr_global (written only in GLOBAL_SETUP/SETDOWN)
+bool g_enforce = true;      // ap-check: allow mfr_global (written only in GLOBAL_SETUP)
+
+void copy(char *out, std::size_t size, const char *text) {
+  if (size) std::snprintf(out, size, "%s", text);
+}
+
+// Dev builds render without the watermark so you can test the look. To see
+// the locked state in a dev build, create the file
+// ~/.afterpresets/native-dev-enforce-license (or start After Effects with
+// AP_DEV_ENFORCE_LICENSE=1) and restart After Effects. Release builds always enforce.
+bool dev_enforce_requested() {
+  if (std::getenv("AP_DEV_ENFORCE_LICENSE")) return true;
+#ifdef _WIN32
+  const char *home = std::getenv("USERPROFILE");
+#else
+  const char *home = std::getenv("HOME");
+#endif
+  if (!home) return false;
+  std::string flag = std::string(home) + "/.afterpresets/native-dev-enforce-license";
+  FILE *f = std::fopen(flag.c_str(), "rb");
+  if (f) std::fclose(f);
+  return f != nullptr;
+}
+
+} // namespace
+
+void start() {
+  if (g_ap) return;
+  ap_config c;
+  ap_config_defaults(&c);
+  c.bundle_id = AP_BUNDLE_ID;
+  c.version = AP_VERSION;
+  c.api_base = AP_API_BASE;
+  c.public_key = AP_PUBLIC_KEY; // Ed25519 public key: verifies, cannot sign
+  c.product_url = AP_PRODUCT_URL[0] ? AP_PRODUCT_URL : nullptr;
+  c.manage_devices_url = AP_MANAGE_DEVICES_URL[0] ? AP_MANAGE_DEVICES_URL : nullptr;
+  c.license_enabled = AP_LICENSE_ENABLED;
+  c.offline_grace_days = AP_OFFLINE_GRACE_DAYS;
+  c.check_in_background = AP_CHECK_IN_BACKGROUND;
+  c.update_mode = AP_UPDATE_MODE;
+  c.dev = AP_DEV_BUILD;     // dev builds never install updates
+  c.build_id = AP_BUILD_ID; // logged at start; `ap dev` reads it to know which build is loaded
+  g_ap = ap_init(&c);       // NULL (config error): stays locked, never crashes
+  g_enforce = AP_LICENSE_ENABLED && (!AP_DEV_BUILD || dev_enforce_requested());
+  ap_apply_staged_update(g_ap); // an update staged in an earlier session
+}
+
+void stop() {
+  ap_log(g_ap, 1, "global setdown"); // lets tools confirm After Effects shut the effect down cleanly
+  ap_apply_staged_update(g_ap); // usually a no-op: updates apply right after download
+  ap_shutdown(g_ap);
+  g_ap = nullptr;
+}
+
+bool unlocked() {
+  if (!g_enforce) return true;
+  return ap_is_unlocked(g_ap) != 0; // NULL runtime: locked
+}
+
+void options_dialog() { ap_options_dialog(g_ap, AP_EFFECT_NAME); }
+
+void status_name(char *out, std::size_t size) {
+  char notice[256] = "";
+  if (g_ap && ap_update_notice(g_ap, notice, sizeof notice) && notice[0]) return copy(out, size, "Update: restart AE");
+  if (!AP_LICENSE_ENABLED) return copy(out, size, "AfterPresets");
+  if (!g_ap) return copy(out, size, "License: unavailable");
+  switch (ap_status_get(g_ap)) {
+  case AP_STATUS_DISABLED: return copy(out, size, "AfterPresets");
+  case AP_STATUS_ACTIVE: return copy(out, size, "License: active");
+  case AP_STATUS_OFFLINE_GRACE: return copy(out, size, "License: offline");
+  case AP_STATUS_SIGNING_IN: return copy(out, size, "License: signing in");
+  case AP_STATUS_CHECKING: return copy(out, size, "License: checking");
+  case AP_STATUS_SIGNED_OUT: return copy(out, size, "License: sign in");
+  default: return copy(out, size, "License: see Options");
+  }
+}
+
+const char *button_label() { return AP_LICENSE_ENABLED ? "License..." : "About..."; }
+
+} // namespace license

package/template/native/src/License.h

@@ -0,0 +1,29 @@
+// Glue between the effect and the AfterPresets runtime (ap_native): license
+// state, the Options dialog, the update notice. Keep this file: it is how
+// buyers sign in and how updates reach them. `ap docs` has the details.
+#pragma once
+
+#include <cstddef>
+
+namespace license {
+
+// PF_Cmd_GLOBAL_SETUP / PF_Cmd_GLOBAL_SETDOWN (main thread).
+void start();
+void stop();
+
+// Any thread, including render threads (lock-free): true when the frame
+// renders without the watermark. Read it once per frame in PreRender.
+bool unlocked();
+
+// Effect > Options, or the status button (main thread). Shows the
+// AfterPresets dialog: license state, Sign in / Buy / Sign out, update notice.
+void options_dialog();
+
+// Short text for the status button's name (at most 31 bytes), e.g.
+// "License: active" or "Update: restart AE". UI thread.
+void status_name(char *out, std::size_t size);
+
+// Caption on the status button.
+const char *button_label();
+
+} // namespace license

package/template/native/src/Render.h

@@ -0,0 +1,68 @@
+// Pixel work for the starter effect: tint toward a colour, blended by mode,
+// optionally along a gradient (centre + angle). One template serves 8, 16 and
+// 32 bits per channel. Pure functions of their inputs, so they are safe for
+// multi-frame rendering (After Effects renders several frames at once).
+#pragma once
+
+#include <cmath>
+#include <cstddef>
+
+struct TintParams {
+  float amount;        // 0..1
+  float r, g, b;       // 0..1
+  int mode;            // AP_MODE_* (1-based popup value)
+  bool gradient;       // fade the tint across the layer
+  float cx, cy;        // gradient centre, in the pixels of the buffers below
+  float dirx, diry;    // unit vector the tint grows along
+  float span;          // pixels over which the gradient goes from 0 to full
+  bool watermark;      // not licensed: draw stripes
+};
+
+template <typename T> inline T clampv(T v, T lo, T hi) { return v < lo ? lo : (v > hi ? hi : v); }
+
+// Premultiplied colour channel blend. s, c in 0..1 (s premultiplied by a).
+inline float blend(int mode, float s, float c, float a) {
+  switch (mode) {
+  case 2: return s + c * a - s * c;  // Screen
+  case 3: return s * c;              // Multiply
+  default: return c * a;             // Tint
+  }
+}
+
+// PixelT: PF_Pixel / PF_Pixel16 / PF_PixelFloat. MAXV: 255, 32768 or 1 (float, unclamped).
+template <typename PixelT, int MAXV, bool FLOAT>
+void tint_rows(const char *src, long src_rowbytes, char *dst, long dst_rowbytes, int width, int height,
+               const TintParams &p) {
+  const float scale = FLOAT ? 1.f : (float)MAXV;
+  for (int y = 0; y < height; ++y) {
+    const PixelT *s = (const PixelT *)(src + (std::ptrdiff_t)y * src_rowbytes);
+    PixelT *d = (PixelT *)(dst + (std::ptrdiff_t)y * dst_rowbytes);
+    for (int x = 0; x < width; ++x) {
+      const float a = s[x].alpha / scale;
+      const float sr = s[x].red / scale, sg = s[x].green / scale, sb = s[x].blue / scale;
+      float t = p.amount;
+      if (p.gradient) {
+        const float along = ((float)x - p.cx) * p.dirx + ((float)y - p.cy) * p.diry;
+        t *= clampv(0.5f + along / p.span, 0.f, 1.f);
+      }
+      float r = sr + (blend(p.mode, sr, p.r, a) - sr) * t;
+      float g = sg + (blend(p.mode, sg, p.g, a) - sg) * t;
+      float b = sb + (blend(p.mode, sb, p.b, a) - sb) * t;
+      if (p.watermark && (((x + y) / 24) & 1)) {
+        r = r * 0.5f + 0.25f * a;
+        g = g * 0.5f + 0.25f * a;
+        b = b * 0.5f + 0.25f * a;
+      }
+      d[x].alpha = s[x].alpha;
+      if (FLOAT) {
+        d[x].red = (decltype(d[x].red))r;
+        d[x].green = (decltype(d[x].green))g;
+        d[x].blue = (decltype(d[x].blue))b;
+      } else {
+        d[x].red = (decltype(d[x].red))clampv(r * scale + 0.5f, 0.f, scale);
+        d[x].green = (decltype(d[x].green))clampv(g * scale + 0.5f, 0.f, scale);
+        d[x].blue = (decltype(d[x].blue))clampv(b * scale + 0.5f, 0.f, scale);
+      }
+    }
+  }
+}