Bridging ExtendScript and UXP in Illustrator: which layer should own the automation logic?

Direct Answer

Put the automation logic in ExtendScript. Use UXP only for the user-facing panel, command palette entries, and any async workflows that require its modern APIs (e.g., `localFileSystem`, `clipboard`, `network`). Bridge the gap with app.doScript(extendScriptString, ScriptLanguage.EXTENDSCRIPT) — this is a documented, supported pattern used in Adobe's own UXP samples. Do not try to replicate the full ExtendScript DOM in UXP; the surface is intentionally smaller and changes per release.

Confirmed Facts vs. Assumptions

• Fact: doScript runs the ExtendScript synchronously inside the Illustrator process and returns a serialized value to the UXP Promise. Complex DOM objects (PageItem, TextFrame, Document) cannot cross the boundary — return plain data (IDs, JSON, primitive arrays) and re-fetch on the calling side.
• Fact: ExtendScript retains the complete Illustrator DOM (all app properties, page-item internals, color profiles, text composers). UXP's require('illustrator') module exposes a curated subset focused on common tasks.
• Fact: Headless batch runs work with ExtendScript on macOS (osascript -e 'tell app "Adobe Illustrator" to do script "..."') and Windows (cscript //nologo script.jsx). UXP requires a running Illustrator instance and has no CLI entry point — structure CI around ExtendScript entry points.
• Assumption (version-dependent): Manifest v5/v6 and Illustrator 2022–2024+ change the UXP API surface (require('illustrator') vs. app.illustrator, permission declarations, entrypoints types). You must re-verify per target version.
• Assumption (sideload fidelity): Sideloaded UXP plugins lose secureStorage and some localFileSystem permissions granted only to signed plugins. Test file I/O flows with the exact manifest permissions you intend to ship.

Recommended Split for Your Case

1. ExtendScript layer (.jsx) — all document manipulation, batch processing, complex DOM traversal, color/profile logic, text-frame composers, any API not present in UXP. Expose small, single-purpose functions that accept/return JSON-serializable data.
2. UXP layer (TypeScript/JS) — panel UI, command entrypoints, user preferences (localStorage), file pickers, clipboard, network calls, orchestration of async user flows. Call ExtendScript via doScript for heavy lifting.
3. Bridge contract — define a tiny JSON RPC-like protocol: {action: 'getLayerTree', params: {docId: 123}} → ExtendScript returns {layers: [...]}. Keep payloads small; avoid circular references.

Local-Only Workflow That Mirrors Distribution

• Develop UXP with UXP Developer Tool (sideload, manifest v5 or v6). Develop ExtendScript in VS Code + ExtendScript Debugger attached to Illustrator.
• Use the same manifest.json permissions you will ship with. Test localStorage persistence across Illustrator restarts — sideloaded plugins clear it on reload; signed plugins do not.
• Run the ExtendScript headless path (osascript/cscript) locally to validate CI batch scripts before committing.

CI Batch Structure

# macOS
osascript -e 'tell application "Adobe Illustrator 2024" to do script "/path/to/batch.jsx"'

# Windows
cscript //nologo //E:jscript "C:\\Path\\batch.jsx"

Do not invoke UXP from CI. If a batch job needs UXP-only APIs (e.g., writing to a user-selected folder via localFileSystem), have the ExtendScript write a sidecar JSON file that a separately triggered UXP command reads on next UI session.

One Missing Diagnostic Detail

Which Illustrator versions (exact major releases, e.g., 27.x, 28.x, 29.x) must this tool support simultaneously? The UXP manifest version (v5 vs. v6) and require('illustrator') surface differ enough that a single codebase may need conditional shims or separate builds per version.