AE Native Gradient Toolkit

Reusable TypeScript and Node tooling for native Adobe After Effects Shape Gradient Fill and Stroke data.

The toolkit provides one reusable implementation for parsing, inspecting, and generating native AE Shape Gradient Fill and Stroke data. It is available under the MIT license.

Current capabilities

• Parse bounded big-endian RIFX files.
• Preserve nested chunk spans, even-byte padding, and trailers outside the declared RIFX boundary.
• Replace one leaf payload and update only affected size words.
• Parse and serialize native LIST(formType="GCky") -> Utf8 gradient XML.
• Normalize complete color and alpha stops, including AE's sixth color-stop extra value.
• Inventory native gradients in .aep and .ffx files and require a unique valid candidate.
• Generate deterministic native Gradient Fill or Stroke .ffx bytes from package-owned templates.
• Verify kind identity, target-header identity, size-field-only prefix changes, output gradient values, suffix bytes, and AE trailer bytes.
• Inspect bounded regular files through the packaged CLI.
• Explain generation with structural and SHA-256 evidence before any write.
• Write through a verified sibling temporary file only with explicit --write; refuse replacement unless --force is present.
• Compare owned AE 26.3 Fill/Stroke fixtures with immutable expected models produced by a pinned independent-oracle validation.
• Resolve ordered exact AEP target descriptors to complete gradients in one bounded parse.
• Materialize the fixture-authenticated implicit AE white-to-black gradient default.
• Ship provenance-approved AE 22.6, AE 25.6, and AE 26.3 template families with immutable integrity metadata.

An external run of the repository's fail-closed live-proof harness on AE 26.3x87 reported passing Gradient Fill and Stroke cases with 2, 3, and 8 stops. The run covered apply, saved-AEP readback, separate Undo, sibling/selection preservation, and owned cleanup. Result artifacts are retained outside this repository, so this is development provenance rather than a reproducible package or broad compatibility claim. Product integration and exact-version compatibility gates remain intentionally pending.

Installation and release status

Package identity: @zimoby/ae-native-gradient@0.2.0.

Install the published release from npm:

npm install @zimoby/ae-native-gradient@0.2.0

The matching immutable source release is v0.2.0. Git consumers can instead resolve the reviewed main commit once and install that full SHA:

TOOLKIT_SHA="$(git ls-remote https://github.com/zimoby/ae-native-gradient-toolkit.git refs/heads/main | cut -f1)"
npm install "git+https://github.com/zimoby/ae-native-gradient-toolkit.git#$TOOLKIT_SHA"

Each npm X.Y.Z release must have a matching immutable vX.Y.Z Git tag pointing to the same source commit.

Third-party validation tooling is intentionally external to this repository. py-aep was used as a pinned MIT-licensed read-only oracle, but its source, adapter, dependency requirements, environment, and regeneration command are not part of this project or package. The repository retains only owned fixtures plus frozen provenance and agreement hashes.

Compatibility

Surface	Contract
Node.js	22.x and 24.x; local development remains pinned to .node-version (22.22.3)
Modules	ESM only
Automated CI	Ubuntu matrix on Node 22.22.3 and current 24.x
AEP identity indexing	Explicit project-format schemas 93..97; unknown formats fail closed
Package templates	Versioned AE 22.6, AE 25.6, and AE 26.3 Fill/Stroke families; product support policy remains consumer-owned
External live-proof provenance	After Effects 26.3x87 on macOS 15.7.1; result artifacts retained outside this repository

The reported AE 26.3 result supports the native Fill/Stroke mechanism for that bounded proof matrix. It is not a claim that every AE version, operating system, or product integration is supported.

Development

npm ci
npm test
npm run build
npm run pack:check

Library use

import { readFile, writeFile } from "node:fs/promises";
import { fileURLToPath } from "node:url";
import { generateGradientFfx } from "@zimoby/ae-native-gradient";

const gradient = {
  schemaVersion: 1,
  colorStops: [
    { offset: 0, midpoint: 0.5, rgb: [1, 0, 0], extra: 0 },
    { offset: 1, midpoint: 0.5, rgb: [0, 0, 1], extra: 0 },
  ],
  alphaStops: [
    { offset: 0, midpoint: 0.5, alpha: 1 },
    { offset: 1, midpoint: 0.5, alpha: 1 },
  ],
};

const templatePath = fileURLToPath(
  import.meta.resolve("@zimoby/ae-native-gradient/templates/fill.ffx"),
);
const templateBytes = new Uint8Array(await readFile(templatePath));
const { bytes, report } = generateGradientFfx(templateBytes, "fill", gradient);
await writeFile("generated-fill.ffx", bytes);
console.log(report.verification);

generateGradientFfx() is pure: it accepts and returns bytes, performs no filesystem access, and emits no hashes. Filesystem policy and hashes belong to the CLI/host adapter.

CLI use

Create gradient.json:

{
  "schemaVersion": 1,
  "colorStops": [
    { "offset": 0, "midpoint": 0.5, "rgb": [1, 0, 0], "extra": 0 },
    { "offset": 1, "midpoint": 0.5, "rgb": [0, 0, 1], "extra": 0 }
  ],
  "alphaStops": [
    { "offset": 0, "midpoint": 0.5, "alpha": 1 },
    { "offset": 1, "midpoint": 0.5, "alpha": 1 }
  ]
}

Each stop list must contain 2–8 entries with nondecreasing offsets. Offsets, midpoints, and alpha values are in [0, 1]; RGB and AE's sixth color-stop extra value must be finite numbers.

Then run:

ae-native-gradient --help
ae-native-gradient inspect --unique /absolute/path/to/file.aep

# Explain only; prints structural and SHA-256 evidence and writes nothing.
ae-native-gradient generate \
  --kind fill \
  --config /absolute/path/to/gradient.json

# Explicit verified write using the package-owned Fill template.
ae-native-gradient generate \
  --kind fill \
  --config /absolute/path/to/gradient.json \
  --write /absolute/path/to/generated.ffx

Use --template /absolute/path/to/template.ffx only when intentionally testing another owned template. Existing outputs are refused unless --force is supplied. The CLI reads only bounded regular files, rejects unsafe output aliases/symlinks, verifies temporary output by readback hash, and leaves no partial destination on handled failure.

Canonical assets

Package subpaths:

• @zimoby/ae-native-gradient/templates/fill.ffx
• @zimoby/ae-native-gradient/templates/stroke.ffx
• @zimoby/ae-native-gradient/templates/ae22-6/fill.ffx
• @zimoby/ae-native-gradient/templates/ae22-6/stroke.ffx
• @zimoby/ae-native-gradient/templates/ae25-6/fill.ffx
• @zimoby/ae-native-gradient/templates/ae25-6/stroke.ffx
• @zimoby/ae-native-gradient/templates/ae26-3/fill.ffx
• @zimoby/ae-native-gradient/templates/ae26-3/stroke.ffx

The unversioned paths remain backward-compatible aliases for the AE 26.3 family. All listed files are package-owned templates, not product-owned copies.

Consumer policy

Verify integration using a packed tarball in a clean temporary consumer, then depend on a reviewed npm version or exact Git commit. Package artifacts include compiled ESM, declarations, matching TypeScript sources and source maps, the CLI, and the six provenance-approved templates. Immutable versions are recommended for reproducibility. The MIT license permits copying, modification, and redistribution.

Support and contributing

Use GitHub Issues for reproducible bugs and feature requests. Include Node/npm versions, AE version when relevant, the command or API call, expected versus actual behavior, and a minimal redistributable fixture when possible. Do not attach sensitive production AEP files publicly.

Focused pull requests are welcome. Run npm ci and npm run check before submitting. New binary fixtures must have explicit ownership, acquisition, hash, and distribution metadata.

Report security issues through GitHub private vulnerability reporting, not a public issue.

License

MIT. See LICENSE.