@enfocussw/switch-scripting-context 25.11.0-beta.9 → 25.11.1-beta.0

package/docs/switch-api/api-versions.md

@@ -0,0 +1,116 @@
+---
+id: api-versions
+category: switch-api
+order: 25
+summary: "Which Switch release added each scripting API class, method, and enum value; API availability follows the running Switch, not `manifest.xml`"
+triggers:
+  - "Writing or reviewing code for a script or app that must run on a Switch version older than the latest, or when the user names a minimum Switch version"
+---
+
+# API availability by Switch version
+
+## The running Switch decides which methods exist
+
+Each Switch installation ships one copy of the scripting module, and every bundled Node.js version
+uses that same copy. So which API methods a script can call depends on the Switch Server the script
+runs on, not on anything in the script package. A script whose `manifest.xml` says `20.1` runs on
+Node.js 12 in Switch 26.07, and it still gets the full 26.07 API.
+
+The two versions are independent:
+
+| Depends on | Decided by |
+|---|---|
+| Node.js version (language features, Node built-ins) | `SwitchVersion` in `manifest.xml`, looked up by the running Switch. See [script-structure.md § Node.js version per Switch version](../switch-project/script-structure.md#nodejs-version-per-switch-version) |
+| Scripting API (classes, methods, enum values below) | The version of the Switch Server the script runs on |
+
+When code must run on an older Switch, check every API call against the tables below for the
+**oldest** Switch version the script or app must support. For an app, that is the version baseline
+from [project-planning.md § Switch version baseline](../switch-project/project-planning.md#switch-version-baseline-apps-only).
+
+### Checking at runtime
+
+`s.getServerVersion()` (Switch 24.0+) returns the running Switch version as a number, e.g. `25.11`.
+It doesn't exist on older Switch versions, so it can't detect those. To use a newer method when
+available and fall back otherwise, test for the method itself:
+
+```ts
+if (typeof job.getVariableAsString === 'function') {
+    // Switch 24.0+
+} else {
+    // fallback for older Switch versions
+}
+```
+
+## Release names
+
+| `SwitchVersion` | Release |
+|---|---|
+| `20.0` | Switch 2020 Spring |
+| `20.1` | Switch 2020 Fall |
+| `21.0` | Switch 2021 Spring |
+| `21.1` | Switch 2021 Fall |
+| `22.0` | Switch 2022 Spring |
+| `22.1` | Switch 2022 Fall |
+| `23.1` | Switch 2023 Fall |
+| `24.0` | Switch 2024 Spring |
+| `24.1` | Switch 2024 Fall |
+| `25.07` | Switch 25.07 |
+| `25.11` | Switch 25.11 |
+| `26.03` | Switch 26.03 |
+| `26.07` | Switch 26.07 |
+
+## Source and limits of this list
+
+The list comes from Enfocus's published type declarations
+(`github.com/enfocus-switch/types-switch-scripting`), diffed from one release's tags to the next.
+Several tags for one release (for example 22.1.0 and 22.1.1) are corrections to the declarations
+for that release, not API changes, so they count as one release. A release with no tag added
+nothing.
+
+- The first tags (1.0.0 and 1.0.1, October 2020) are the baseline. The declarations don't separate
+  Switch 2020 Spring from 2020 Fall, so treat the baseline as available in every Switch version
+  that runs Node.js scripts.
+- Tag 1.1.0 (May 2021) is Switch 2021 Spring. The later tags carry the release number (21.1.x,
+  22.0.x, 22.1.x, 24.0.x, 24.1.x).
+- The declarations end at v24.1.1-final (Switch 2024 Fall). SwitchScriptTool 26.07 still scaffolds
+  that version. A check of the Switch 26.07 scripting module found no public class, method, or enum
+  value that v24.1.1 lacks. So nothing was added in 23.1, 25.07, 25.11, 26.03, or 26.07.
+- Entry points aren't part of the type declarations, so this list doesn't record when each entry
+  point appeared. The webhook entry points (`httpRequestTriggeredSync`/`Async`) need
+  `s.httpRequestSubscribe()`, so they can't be used before Switch 21.1 either.
+
+## Baseline (every Switch version with Node.js scripting)
+
+| Class | Members |
+|---|---|
+| `Switch` | `getGlobalData`, `setGlobalData`, `removeGlobalData` (including the `lock` parameter) |
+| `FlowElement` | `getPropertyStringValue`, `getPropertyType`, `getPropertyDisplayName`, `hasProperty`, `getOutConnections`, `setTimerInterval`, `log`, `failProcess`, `createJob`, `getPluginResourcesPath` |
+| `Job` | `getName`, `getId`, `isFile`, `isFolder`, `get`, `sendToNull`, `sendToSingle`, `sendTo`, `sendToData`, `sendToLog`, `fail`, `log`, `createChild`, `getPrivateData`, `setPrivateData`, `removePrivateData`, `listDatasets`, `createDataset`, `getDataset`, `removeDataset` |
+| `Connection` | `getId`, `getName`, `getPropertyStringValue`, `getPropertyType`, `getPropertyDisplayName`, `hasProperty` |
+| Enums | `AccessLevel` (all), `Connection.Level` (all), `PropertyType` (all), `LogLevel.Info`/`Warning`/`Error`, `DatasetModel.Opaque`/`XML`/`XMP`/`JDF`, `Scope.Element`/`FlowElement`/`Global` |
+
+## Added per release
+
+| Release | Added |
+|---|---|
+| 21.0 | `flowElement.getJobs()`; `PdfDocument` and `PdfPage` (whole classes); `EnfocusSwitchPrivateDataTag` with `hierarchy`, `emailAddresses`, `emailBody`, `userName`, `userFullName`, `userEmail`, `origin`; `LogLevel.Debug` |
+| 21.1 | `flowElement.getName()`; `HttpRequest` and `HttpResponse` (whole classes, including `HttpRequest.Method`); `s.httpRequestSubscribe()`, `s.httpRequestUnsubscribe()`; `ImageDocument` (whole class, including `ImageDocument.ColorMode` and `ImageDocument.ColorSpace`); `EnfocusSwitchPrivateDataTag.initiated`, `.submittedTo` |
+| 22.0 | `flowElement.getFlowName()`; `Switch.tr()`; `XmlDocument` (whole class); `Scope.Flow`, `Scope.FlowElements`; `DatasetModel.JSON` |
+| 22.1 | `job.getPriority()`, `job.setPriority()`, `Priority` enum; `job.sendToChannel()`, `flowElement.subscribeToChannel()`; `job.processLater()`; `s.setAbortData()`; `XmpDocument` (whole class), `pdfDocument.getXMP()`; `EnfocusSwitchPrivateDataTag.state` |
+| 23.1 | Nothing |
+| 24.0 | `flowElement.getScriptDataPath()`, `flowElement.createPathWithName()`; `job.getVariableAsString()`, `job.getxmlData()`, `job.getxmpData()`, `job.getJdfData()`, `job.getJSONData()`; `s.getPreferenceSetting()`, `s.getServerVersion()`; `NoYesListPropertyStringValue` |
+| 24.1 | `connection.getType()`, `connection.getFileCount()`, `flowElement.getFileCount()` |
+| 25.07, 25.11, 26.03, 26.07 | Nothing |
+
+## Declaration changes to existing methods
+
+These signatures changed between releases in the declarations. The declarations don't say whether
+older runtimes enforced the older signature, so when targeting a release before the change, write
+code that satisfies both.
+
+- Before 21.0, private data and global data values were declared as `string`; from 21.0 they are
+  `any`. On 20.x, store strings (for example `JSON.stringify` the value) and parse them on read.
+- Before 21.0, `job.fail()` declared `messageParams` as required. On 20.x, pass an array, even an
+  empty one.
+- Before 22.1, `flowElement.failProcess()` declared `messageParam` as a required `string`. On an
+  older Switch, pass a string.

package/docs/switch-api/connection.md

@@ -0,0 +1,82 @@
+---
+id: connection
+category: switch-api
+order: 6
+summary: "`Connection`: type, properties, file count"
+triggers:
+  - "Routing to specific connections or reading connection properties"
+---
+
+# Connection Class
+
+A `Connection` represents an outgoing connection from the flow element. Obtain instances via `flowElement.getOutConnections()`.
+
+## Identity
+
+```ts
+connection.getId(): string
+```
+Unique ID for the connection. Stable across deactivate/reactivate, Switch restarts, holding/releasing connections, and renaming the flow itself. Changes on export/re-import, a flow upgrade, or renaming the flow *element* (not the flow).
+
+```ts
+connection.getName(): string
+```
+Display name as shown on the canvas. May be an empty string.
+
+```ts
+// Switch 24.1+
+connection.getType(): string
+```
+Connection type. One of: `"Move"`, `"Filter"`, `"Traffic-data"`, `"Traffic-log"`, `"Traffic-datawithlog"`.
+
+## Connection properties
+
+Connection properties are declared in the script's XML declaration (`ConnectionFields`) and configured per-connection in the canvas. See [script-declaration.md](../switch-project/script-declaration.md) for how to declare them (via SwitchScripter).
+
+```ts
+connection.getPropertyStringValue(tag: string): Promise<string | string[]>
+```
+Returns the connection property value as a string. Throws `"Invalid tag: <tag>"` if the tag is unknown **or if it's a `Dependency` dependent currently hidden by its master's value** — see [script-declaration.md § Dependency](../switch-project/script-declaration.md#custom-property-elements-elementfields). Before fetching a dependent property, confirm its condition holds (from the already-read master value, or via `hasProperty(tag)` below) rather than fetching it unconditionally.
+
+This is **not** how to check which traffic light level(s) a connection accepts before calling `job.sendToData()` — `"Success"`/`"Warning"`/`"Error"` are not property tags, so passing one throws the same invalid-tag error. There is no supported way to check in advance; see [Connection.Level enum](#connectionlevel-enum) below.
+
+```ts
+connection.getPropertyType(tag: string): PropertyType
+```
+Returns the `PropertyType` of the property.
+
+```ts
+connection.getPropertyDisplayName(tag: string): string
+```
+Returns the English display name of the property (for use in log messages).
+
+```ts
+connection.hasProperty(tag: string): boolean
+```
+Returns `true` if the property exists and is visible for the current configuration. Use this to guard `getPropertyStringValue(tag)` calls on `Dependency` dependents — see the note above.
+
+## File count
+
+```ts
+// Switch 24.1+
+connection.getFileCount(nested?: boolean): Promise<number>
+```
+Returns the number of files in the folder at the other end of this connection. If `nested` is `false`, counts only direct children; if `true` (the default, so it can be omitted), counts recursively (subfolders themselves are not counted).
+
+## Connection.Level enum
+
+Used with `job.sendToData()` and `job.sendToLog()` to select which traffic light connection a job routes to.
+
+| Value | String |
+|---|---|
+| `Connection.Level.Success` | `"success"` |
+| `Connection.Level.Warning` | `"warning"` |
+| `Connection.Level.Error` | `"error"` |
+
+Available as `EnfocusSwitch.Connection.Level.*` outside `main.ts`.
+
+**Traffic light levels are not a readable connection property.** `flowElement.getOutConnections()`
+returns the outgoing `Connection` objects, but the supported API has no way to determine which
+level(s) a given connection accepts. Don't call `connection.getPropertyStringValue("Success")`, `"Warning"`, or `"Error"` expecting to
+read this back; those are not valid property tags for a traffic light connection. To route
+optionally, see [job-patterns.md § Sending jobs](job-patterns.md#sending-jobs).

package/docs/switch-api/{api-document-classes.md → document-classes.md}

@@ -1,7 +1,18 @@
+---
+id: document-classes
+category: switch-api
+order: 9
+summary: "`PdfDocument`, `PdfPage`, `ImageDocument`, `XmlDocument`, `XmpDocument`: read-only file introspection"
+triggers:
+  - "Inspecting PDF, image, XML, or XMP file contents"
+---
+
 # Document Classes
 
 Read-only document introspection utilities. All methods may throw — wrap in `try/catch`. Load this file when working with PDF, image, XML, or XMP documents.
 
+Each class needs a minimum Switch version: `PdfDocument` and `PdfPage` 21.0+, `ImageDocument` 21.1+, `XmlDocument` 22.0+, `XmpDocument` and `doc.getXMP()` 22.1+.
+
 ## PdfDocument
 
 Open a PDF to inspect metadata and page geometry.
@@ -31,7 +42,7 @@ doc.getSecurityMethod(): string
 PdfDocument.getSecurityMethod(path: string): string
 
 doc.getPage(pageNumber?: number): PdfPage          // 1-based; defaults to page 1
-doc.getXMP(): XmpDocument
+doc.getXMP(): XmpDocument                          // Switch 22.1+
 ```
 
 ### Static page dimension methods
@@ -121,7 +132,7 @@ img.getSamplesPerPixel(): number
 ImageDocument.getSamplesPerPixel(path: string): Promise<number>
 ```
 
-See [api-enums.md](api-enums.md) for `ImageDocument.ColorMode` and `ImageDocument.ColorSpace` values.
+See [enums.md](enums.md) for `ImageDocument.ColorMode` and `ImageDocument.ColorSpace` values.
 
 ---
 

package/docs/switch-api/entry-points.md

@@ -0,0 +1,171 @@
+---
+id: entry-points
+category: switch-api
+order: 2
+summary: "All entry point signatures, constraints, and when each is called"
+triggers:
+  - "Scaffolding a script, adding/editing an entry point, or making any edit to main.ts/main.js"
+---
+
+# Switch Script Entry Points
+
+Entry points are top-level `async` functions with specific names. They are **not exported**. Switch calls them automatically based on flow events.
+
+## Entry-point scanner constraints
+
+Switch discovers a script's entry points by regex, not by parsing. Before matching
+`function\s+(name)\s*\(` it strips comments and literals with a regex that doesn't understand JS
+escaping. Certain source shapes make that strip regex delete large spans of real code — and every
+`function` declaration inside the deleted span becomes invisible to Switch, whether or not that
+function is itself well-formed.
+
+This applies to **every** entry point on this page, not only the four checked below — a swallowed
+`validateProperties` or `getLibraryForProperty` fails silently (the callback just never runs, no
+error anywhere), which is worse than the loud failure the four below produce. The one exception is
+`calculateScriptExpression`: it's invoked directly at runtime rather than through this scanner, so
+it isn't at risk.
+
+If none of `jobArrived`, `timerFired`, `flowStopTriggered`, `httpRequestTriggeredAsync` survives,
+Switch fails with `Cannot open script '<name>': no entry points found` — `httpRequestTriggeredSync`
+alone does not satisfy this check. Both the packed `.sscript` (the entry-point list is baked in at
+pack time) and the unpacked script folder (`main.js` is rescanned by this same scanner every time
+Switch loads it, e.g. running or debugging from Designer) are affected. Packing does not validate
+or warn about any of this — a script that packs cleanly can still fail to load.
+
+**Rules for writing entry points in `main.ts`/`main.js`:**
+
+1. Never write a string literal whose content ends with a backslash: `"\\"`, `'\\'`, `` `\\` ``,
+   `"C:\\Temp\\"`. This is the highest-frequency trigger — the strip regex hunts for the next
+   matching quote character anywhere later in the file to close the literal (a backslash right
+   before the real closing quote makes it skip past that quote), and deletes everything in between.
+   Use `"\x5c"`, `"\u005C"`, `String.fromCharCode(92)`, or restructure (e.g.
+   `JSON.stringify(v).slice(1, -1)` for backslash/quote escaping) instead. A backslash elsewhere in
+   the literal is fine: `"\\n is newline"`, `"a\\b"`.
+2. Avoid regex literals — including ones that look properly closed, like `/[^/]+/` (a character
+   class containing an unescaped `/`). The strip regex doesn't understand character classes, so it
+   closes the "literal" early at the inner `/` and leaves a dangling `/` that swallows forward to
+   the next `/` anywhere later in the file. Use `new RegExp("...")` instead.
+3. Avoid division that isn't in the plain `word / word` shape. `a / b` is recognised and stripped
+   safely; `) / 2`, `] / 2`, and `/=` are not, and the leftover `/` swallows forward exactly like an
+   unclosed regex literal. Rewrite as `Math.floor(x / y)` with plain identifiers, or hoist to a
+   named variable first.
+4. Declare every entry point with the literal `function` keyword at top level:
+   `function jobArrived(...)` or `async function jobArrived(...)`. Arrow functions,
+   `exports.jobArrived = function (...)`, and class methods are invisible to the scanner.
+5. Entry-point names are matched case-sensitively. `JobArrived` is silently dropped during
+   extraction — if another valid entry point is also present the script packs and loads without
+   error, the misnamed function just never runs.
+
+See [tooling.md § Verify entry points before packing](../switch-project/tooling.md#verify-entry-points-before-packing)
+for a script to catch this before it reaches Switch.
+
+## Flow lifecycle
+
+```ts
+async function flowStartTriggered(s: Switch, flowElement: FlowElement): Promise<void>
+```
+Called when the flow starts. Use to subscribe to webhooks (`s.httpRequestSubscribe`) or channels (`flowElement.subscribeToChannel`). Cannot coexist with `timerFired` or `jobArrived` as the sole entry point. May execute in parallel for concurrent elements. Not available for debugging.
+
+```ts
+async function flowStopTriggered(s: Switch, flowElement: FlowElement): Promise<void>
+```
+Called when the flow stops. May execute in parallel for concurrent elements. Not available for debugging.
+
+## Timer
+
+```ts
+async function timerFired(s: Switch, flowElement: FlowElement): Promise<void>
+```
+Called on a recurring timer. First fires after `flowStartTriggered`. Set the interval via `flowElement.setTimerInterval(seconds)`. Cannot coexist with `flowStartTriggered` as the sole entry point.
+
+Required when `IncomingConnections="No"`; optional (alongside `jobArrived`) when
+`IncomingConnections="Yes"`. Never leave it present but empty — remove it entirely if it does
+nothing.
+
+## Job processing
+
+```ts
+async function jobArrived(s: Switch, flowElement: FlowElement, job: Job): Promise<void>
+```
+Called when a job arrives. Must eventually call a `job.sendTo*()` or `job.fail()`. Can run concurrently if configured in the script XML declaration.
+
+`jobArrived` and `timerFired` presence must match the declared connections — present when
+`IncomingConnections="Yes"` (`timerFired` may additionally be present); when
+`IncomingConnections="No"`, `timerFired` must be present instead. See
+[script-declaration.md](../switch-project/script-declaration.md#built-in-elementfields). Never leave an empty
+`jobArrived` or `timerFired` in the script — remove the function entirely if it does nothing.
+
+**Gotcha: a flow restart replays every queued job through `jobArrived` again.** This includes a job
+whose real processing was deferred elsewhere, such as a job registered in global data and actually
+handled later in `timerFired`. `jobArrived` does not skip a job just because it was already
+registered on a previous run; if the element still has a large backlog queued when the flow
+restarts, every one of those jobs fires `jobArrived` again, and working through a long backlog this
+way can take a long time even when each invocation only needs to recognize the job as already
+registered and return. A script that defers processing this way must check global data at the top
+of `jobArrived` and return immediately for a job already registered there, rather than assuming
+`jobArrived` fires exactly once per job.
+
+```ts
+async function abort(s: Switch, flowElement: FlowElement, job: Job, abortData: any): Promise<void>
+```
+Called when an entry point exceeds its configured timeout. The `abortData` value was set beforehand via `s.setAbortData()` (Switch 22.1+). Maximum execution: 60 seconds, after which the script executor is killed. Applies to: `jobArrived`, `timerFired`, `httpRequestTriggeredSync`, `httpRequestTriggeredAsync`, `flowStartTriggered`, `flowStopTriggered`.
+
+## Webhooks
+
+Both webhook entry points need Switch 21.1+, the first release with `s.httpRequestSubscribe()`.
+
+```ts
+async function httpRequestTriggeredSync(request: HttpRequest, args: any[], response: HttpResponse, s: Switch): Promise<void>
+```
+Synchronous webhook handler. A response **must** be sent before the function returns. Registered via `s.httpRequestSubscribe()` in `flowStartTriggered`. Executes in concurrent mode. Request body limit: 1 MB (HTTP 413). Queue limit: 10,000 pending requests (HTTP 429). Execution timeout: 1 minute (HTTP 524). Default response if none set: HTTP 200 with `{"status": true}`.
+
+```ts
+async function httpRequestTriggeredAsync(request: HttpRequest, args: any[], s: Switch, flowElement: FlowElement): Promise<void>
+```
+Asynchronous webhook handler. No response is required. Registered via `s.httpRequestSubscribe()` in `flowStartTriggered`. Only invoked if `httpRequestTriggeredSync` is not defined, or if the sync handler returned a 2xx status.
+
+## Script expression
+
+```ts
+async function calculateScriptExpression(s: Switch, flowElement: FlowElement, job: Job): Promise<string | number | boolean>
+```
+Called to evaluate a script expression for the flow element. The return value is used as the expression result.
+
+## Property UI callbacks
+
+Not available for debugging.
+
+```ts
+async function getLibraryForProperty(s: Switch, flowElement: FlowElement, tag: string): Promise<string[]>
+```
+Returns a dynamic list of values for a property's library dropdown. Mandatory if any property uses
+the `askplugin`/`askplugin2` editor (see
+[property-editors.md](../switch-project/property-editors.md#modal-editors)). Log an error via `flowElement.log()`
+if the list would otherwise come back empty, so the user can see why the dropdown has nothing in it.
+
+```ts
+async function getLibraryForConnectionProperty(s: Switch, flowElement: FlowElement, c: Connection, tag: string): Promise<string[]>
+```
+Returns a dynamic list of values for a connection property's library dropdown. Same guidance as
+`getLibraryForProperty` above, for connection fields using `askplugin`/`askplugin2`.
+
+```ts
+async function validateProperties(s: Switch, flowElement: FlowElement, tags: string[]): Promise<{ tag: string, valid: boolean }[]>
+```
+Validates one or more property values. Return one result object per tag. Mandatory if any property
+declares `Validation="Custom"` or `"Standard and custom"` (see
+[script-declaration.md](../switch-project/script-declaration.md#custom-property-elements-elementfields)). Log
+an error via `flowElement.log()` for any tag returned with `valid: false`, so the user sees why.
+
+```ts
+async function validateConnectionProperties(s: Switch, flowElement: FlowElement, c: Connection, tags: string[]): Promise<{ tag: string, valid: boolean }[]>
+```
+Validates one or more connection property values. Same guidance as `validateProperties` above, for
+connection fields declaring `Validation="Custom"`/`"Standard and custom"`.
+
+```ts
+async function findExternalEditorPath(s: Switch, flowElement: FlowElement, tag: string): Promise<string>
+```
+Resolves the path to an external editor for a property. Required whenever the
+`external`/`external2`/… editor is used, unless the dependent `Application` property is non-empty —
+see [property-editors.md § Notes](../switch-project/property-editors.md#notes).

package/docs/switch-api/{api-enums.md → enums.md}

@@ -1,6 +1,15 @@
+---
+id: enums
+category: switch-api
+order: 8
+summary: "All enums with string values (`LogLevel`, `AccessLevel`, `DatasetModel`, `Scope`, `Priority`, `Connection.Level`, etc.)"
+triggers:
+  - "Looking up enum values"
+---
+
 # Switch Scripting Enums
 
-All enums are available globally in `main.ts`. They are also accessible via `EnfocusSwitch.*` when used outside `main.ts` (e.g. in imported modules).
+All enums are available globally in `main.ts`. They are also accessible via `EnfocusSwitch.*` when used outside `main.ts` (e.g. in imported modules). Enums and values without a Switch version below exist in every Switch version with Node.js scripting; see [api-versions.md](api-versions.md).
 
 ## LogLevel
 
@@ -11,7 +20,7 @@ Used with `job.log()` and `flowElement.log()`.
 | `LogLevel.Info` | `"info"` |
 | `LogLevel.Warning` | `"warning"` |
 | `LogLevel.Error` | `"error"` |
-| `LogLevel.Debug` | `"debug"` |
+| `LogLevel.Debug` | `"debug"` (Switch 21.0+) |
 
 ## AccessLevel
 
@@ -32,7 +41,7 @@ Used with `job.createDataset()`, `job.sendToLog()`, and `job.listDatasets()`.
 | `DatasetModel.XML` | `"XML"` |
 | `DatasetModel.XMP` | `"XMP"` |
 | `DatasetModel.JDF` | `"JDF"` |
-| `DatasetModel.JSON` | `"JSON"` |
+| `DatasetModel.JSON` | `"JSON"` (Switch 22.0+) |
 
 ## Scope
 
@@ -41,14 +50,14 @@ Used with `s.getGlobalData()`, `s.setGlobalData()`, `s.removeGlobalData()`.
 | Value | String |
 |---|---|
 | `Scope.Element` | `"element"` |
-| `Scope.Flow` | `"flow"` |
+| `Scope.Flow` | `"flow"` (Switch 22.0+) |
 | `Scope.FlowElement` | `"flowElement"` |
-| `Scope.FlowElements` | `"flowElements"` |
+| `Scope.FlowElements` | `"flowElements"` (Switch 22.0+) |
 | `Scope.Global` | `"global"` |
 
 ## Priority
 
-Used with `job.setPriority()` / `job.getPriority()`.
+Used with `job.setPriority()` / `job.getPriority()`. Switch 22.1+.
 
 | Value | Number |
 |---|---|
@@ -68,11 +77,13 @@ Used with `job.sendToData()` and `job.sendToLog()` for traffic light connections
 | `Connection.Level.Warning` | `"warning"` |
 | `Connection.Level.Error` | `"error"` |
 
-Also available as `EnfocusSwitch.Connection.Level.*` outside `main.ts`.
+Also available as `EnfocusSwitch.Connection.Level.*` outside `main.ts`. It selects which level to
+route to; it is not a property you can read back from a `Connection` object, see
+[connection.md § Connection.Level enum](connection.md#connectionlevel-enum).
 
 ## HttpRequest.Method
 
-Used with `s.httpRequestSubscribe()` and `s.httpRequestUnsubscribe()`.
+Used with `s.httpRequestSubscribe()` and `s.httpRequestUnsubscribe()`. Switch 21.1+.
 
 | Value | String |
 |---|---|
@@ -103,7 +114,7 @@ Returned by `flowElement.getPropertyType()` and `connection.getPropertyType()`.
 
 ## NoYesListPropertyStringValue
 
-Convenience for `Boolean`-typed properties returned as strings.
+Convenience for `Boolean`-typed properties returned as strings. Switch 24.0+.
 
 | Value | String |
 |---|---|
@@ -112,7 +123,7 @@ Convenience for `Boolean`-typed properties returned as strings.
 
 ## EnfocusSwitchPrivateDataTag
 
-Well-known tags for `job.getPrivateData()` / `job.setPrivateData()`.
+Well-known tags for `job.getPrivateData()` / `job.setPrivateData()`. The enum needs Switch 21.0+; `initiated` and `submittedTo` need 21.1+, and `state` needs 22.1+.
 
 | Value | String |
 |---|---|
@@ -129,7 +140,7 @@ Well-known tags for `job.getPrivateData()` / `job.setPrivateData()`.
 
 ## ImageDocument.ColorMode
 
-Used with `ImageDocument.getColorMode()`. Available as `EnfocusSwitch.ImageDocument.ColorMode.*` outside `main.ts`.
+Used with `ImageDocument.getColorMode()`. Available as `EnfocusSwitch.ImageDocument.ColorMode.*` outside `main.ts`. Switch 21.1+.
 
 | Value | String |
 |---|---|
@@ -145,7 +156,7 @@ Used with `ImageDocument.getColorMode()`. Available as `EnfocusSwitch.ImageDocum
 
 ## ImageDocument.ColorSpace
 
-Used with `ImageDocument.getColorSpace()`. Available as `EnfocusSwitch.ImageDocument.ColorSpace.*` outside `main.ts`.
+Used with `ImageDocument.getColorSpace()`. Available as `EnfocusSwitch.ImageDocument.ColorSpace.*` outside `main.ts`. Switch 21.1+.
 
 | Value | String |
 |---|---|

package/docs/switch-api/{api-execution-environment.md → execution-environment.md}

@@ -1,13 +1,38 @@
+---
+id: execution-environment
+category: switch-api
+order: 17
+summary: "Execution modes (`Concurrent`/`Serialized`, `ExecutionGroup`, `NumberOfSlots`), process/concurrency model, state persistence across job invocations, unhandled-rejection behavior, npm/native module constraints"
+triggers:
+  - "Choosing or changing an execution mode, relying on module-level state across jobs, handling errors/rejections, or using third-party npm packages"
+---
+
 # Execution Environment
 
-How the Node.js process a script runs in behaves, beyond the entry point API itself. These are
-consequences of the host process model, not things a script configures — understanding them avoids
-subtle bugs around state persistence and error handling.
+How the Node.js process a script runs in behaves, beyond the entry point API itself. Apart from the
+execution mode below, these are consequences of the host process model rather than things a script
+configures — understanding them avoids subtle bugs around state persistence and error handling.
+
+## Execution modes
+
+Set in the XML declaration via SwitchScripter, or by editing it directly (see
+[script-declaration.md](../switch-project/script-declaration.md#built-in-elementfields)). Applies to all
+instances of the script.
+
+**Concurrent** — entry points for the same or different instances may run in parallel. Scripts must
+synchronize access to any shared resources. `NumberOfSlots` is only meaningful in this mode.
+
+**Serialized** — entry points within the same **execution group** are never concurrent. Instances
+in different execution groups may still run in parallel.
+
+**Execution group** — only relevant for Serialized mode. Should be a reverse-domain string (e.g.
+`com.mycompany.myScript`) to avoid collisions. Defaults to the Script ID if left empty.
+
+Neither setting maps to a count of Node.js OS processes — see below.
 
 ## Two independent concurrency tiers
 
-`NumberOfSlots`/`ExecutionGroup` (see
-[Execution modes](api-script-structure.md#execution-modes)) and the pool of Node.js processes that
+`NumberOfSlots`/`ExecutionGroup` (above) and the pool of Node.js processes that
 actually run script code are governed completely separately — there is no one-to-one mapping between
 them:
 
@@ -23,7 +48,7 @@ them:
   whichever pooled executor is free (or a new one is spawned if none are); executors are reused
   across many jobs and across different flow elements running the same Node.js version, until
   recycled (see
-  [Executor cleanup thresholds](api-job-patterns.md#executor-cleanup-thresholds)).
+  [Executor cleanup thresholds](job-patterns.md#executor-cleanup-thresholds)).
 
 ## Module-level state persists across jobs on the same executor
 
@@ -46,25 +71,27 @@ underlying executor process is **not** killed and continues serving subsequent j
 including for other flow elements pooled onto the same executor. Don't rely on an unhandled
 rejection to surface as a hard failure of the whole executor; always catch and handle errors
 explicitly (e.g. via `job.fail()`/`flowElement.failProcess()` — see
-[api-logging.md](api-logging.md)) rather than letting a promise reject unhandled.
+[logging.md](logging.md)) rather than letting a promise reject unhandled.
 
 ## Third-party npm modules: file-based scripts only
 
 A script **expression** (entered inline in a flow element property, not a file-based script/app —
-see [Script expression](api-entry-points.md#script-expression)) cannot use third-party npm modules
+see [Script expression](entry-points.md#script-expression)) cannot use third-party npm modules
 at all; only Node.js built-ins are available via `require`. A file-based script/app can use
 third-party modules from its own `node_modules` folder (see
-[Script folder files](api-script-structure.md#script-folder-files)).
+[Script folder files](../switch-project/script-structure.md#script-folder-files)).
 
 ## Native (binary) addons are not supported
 
-Scripts with ESM dependencies are bundled before execution; this bundling path does not support
+Scripts with ESM dependencies are bundled before execution, when `SwitchVersion` in `manifest.xml`
+is `24.0` or higher (see
+[script-structure.md § Other effects of `SwitchVersion`](../switch-project/script-structure.md#other-effects-of-switchversion)); this bundling path does not support
 native/binary Node addons (`.node` files). Stick to pure-JavaScript/TypeScript dependencies.
 
 ## No explicit CPU or memory cap beyond the documented thresholds
 
 Beyond the entry-point abort timeout and executor recycling thresholds already documented (see
-[Job processing](api-entry-points.md#job-processing) and
-[Executor cleanup thresholds](api-job-patterns.md#executor-cleanup-thresholds)), there is no
+[Job processing](entry-points.md#job-processing) and
+[Executor cleanup thresholds](job-patterns.md#executor-cleanup-thresholds)), there is no
 additional CPU-time or memory limit enforced on a script's own code. A runaway loop or leak is
 bounded only by those thresholds, not stopped proactively.