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

package/docs/{switch-api/api-vscode.md → switch-project/vscode.md}

@@ -1,3 +1,12 @@
+---
+id: vscode
+category: switch-project
+order: 13
+summary: "Type declarations, tsconfig for TypeScript 6, ESLint rules"
+triggers:
+  - "Setting up VS Code or fixing type errors"
+---
+
 # VS Code Setup
 
 ## Type declarations
@@ -14,6 +23,16 @@ Enables autocomplete and type checking for `Switch`, `Job`, `FlowElement` and al
 
 > `SwitchScriptTool --create` sets this up automatically for new TypeScript script folders.
 
+v24.1.1-final is the last published version and matches the API of every Switch release from 24.1
+to 26.07. It declares every method without marking which Switch release added it, so the compiler
+won't flag a call that an older target Switch lacks. Check those against
+[api-versions.md](../switch-api/api-versions.md).
+
+SwitchScriptTool 26.07 also scaffolds `@types/node` 24.x whatever Node.js version the script will
+run on. When the package will run on an older Node.js (see
+[script-structure.md § Node.js version per Switch version](script-structure.md#nodejs-version-per-switch-version)),
+pin `@types/node` to that major version so the compiler flags newer Node.js APIs.
+
 ## TypeScript 6 / VS Code 1.114+
 
 From VS Code 1.114, TypeScript 6 is used. Ambient/global types are no longer auto-included — without explicit configuration, `@types/node` and `@types/switch-scripting` globals (`Switch`, `Job`, etc.) will not be recognised.

package/docs/switch-scripting.md

@@ -3,38 +3,64 @@ Enfocus Switch workflow automation scripts written in TypeScript/Node.js.
 
 ## Execution environment
 - Entry points are top-level `async` functions with specific names — **not exported** — executed in a `node:vm.Script()` context.
-- ESM is supported: if ES modules are present the script is bundled with ESBuild before running.
-- Type declarations are in `node_modules/@types/switch-scripting/index.d.ts` and must be followed precisely.
+- ESM is supported: if ES modules are present the script is bundled with ESBuild before running (when `SwitchVersion` in `manifest.xml` is `24.0` or higher).
+- Type declarations are in `node_modules/@types/switch-scripting/index.d.ts` and must be followed precisely. They list every method up to Switch 24.1 without saying which release added it.
+- The Node.js version comes from `SwitchVersion` in `manifest.xml`; the available API methods come from the Switch version the script runs on. See `switch-project/script-structure.md` and `switch-api/api-versions.md`.
 
 ## API reference
-Detailed API docs are in `docs/switch-api/`:
+Detailed docs live in three folders, alongside this file: `switch-api/` (the scripting API itself),
+`switch-project/` (script/app project structure and tooling), and `switch-appstore/` (Appstore
+publishing guidance).
 
+<!-- docs-index:table begin -->
 | File | Contents | Load when |
 |---|---|---|
-| `switch-api/api-entry-points.md` | All entry point signatures, constraints, and when each is called | Scaffolding a new script or adding an entry point |
-| `switch-api/api-switch.md` | `Switch` (`s`) — global data, webhooks, abort, server utilities | Using global data, webhooks, abort, or server settings |
-| `switch-api/api-flow-element.md` | `FlowElement` — properties, connections, job creation, logging | Reading properties, creating jobs, logging, connections |
-| `switch-api/api-job.md` | `Job` — routing, file access, child jobs, private data, datasets | Processing/routing jobs, file access, private data, datasets |
-| `switch-api/api-connection.md` | `Connection` — type, properties, file count | Routing to specific connections or reading connection properties |
-| `switch-api/api-http.md` | `HttpRequest` / `HttpResponse` + webhook pattern | Handling incoming HTTP webhooks |
-| `switch-api/api-enums.md` | All enums with string values (`LogLevel`, `AccessLevel`, `DatasetModel`, `Scope`, `Priority`, `Connection.Level`, etc.) | Looking up enum values |
-| `switch-api/api-document-classes.md` | `PdfDocument`, `PdfPage`, `ImageDocument`, `XmlDocument`, `XmpDocument` — read-only file introspection | Inspecting PDF, image, XML, or XMP file contents |
-| `switch-api/api-script-structure.md` | Script folder/package files, manifest format, App vs Script, execution modes | Setting up a new script project or converting to an App |
-| `switch-api/api-tooling.md` | SwitchScriptTool commands, script folder vs package, build and deployment | Creating, building, packaging, or deploying a script |
-| `switch-api/api-debugging.md` | Enabling debug mode in Switch Designer, debuggable entry points, VS Code attach | Debugging a script |
-| `switch-api/api-vscode.md` | Type declarations, tsconfig for TypeScript 6, ESLint rules | Setting up VS Code or fixing type errors |
-| `switch-api/api-script-declaration.md` | XML declaration reference: properties, connections, execution config — agents may edit this file directly | Understanding, adding, or editing script properties/connections/execution config |
-| `switch-api/api-property-editors.md` | Property editor types, string return values, literal editors, dropdowns | Defining property editors in XML or reading property values in code |
-| `switch-api/api-job-patterns.md` | File access semantics, temp cleanup, routing rules, child jobs, executor limits | Processing jobs, creating child jobs, routing to multiple connections |
-| `switch-api/api-execution-environment.md` | Process/concurrency model, state persistence across job invocations, unhandled-rejection behavior, npm/native module constraints | Relying on module-level state across jobs, handling errors/rejections, or using third-party npm packages |
-| `switch-api/api-logging.md` | Log level semantics, logging practice, `console.log` limitation, common gotchas | Adding or reviewing `job.log()`/`flowElement.log()`/`job.fail()`/`failProcess()` calls |
-| `switch-api/api-logs-and-dataroot.md` | Locating the Application Data Root, querying `ServerLogs.db3` directly | Diagnosing or validating a script from its actual log output rather than by reading the code |
+| `switch-project/project-planning.md` | Pre-scaffolding checklist: Script vs App, job-processing approach, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk | Starting a new script or app, before scaffolding any files |
+| `switch-api/entry-points.md` | All entry point signatures, constraints, and when each is called | Scaffolding a script, adding/editing an entry point, or making any edit to main.ts/main.js |
+| `switch-api/switch.md` | `Switch` (`s`): global data, webhooks, abort, server utilities | Using global data, webhooks, abort, or server settings |
+| `switch-api/flow-element.md` | `FlowElement`: properties, connections, job creation, logging | Reading properties, creating jobs, logging, connections |
+| `switch-api/job.md` | `Job` **signatures**: routing, file access, child jobs, private data, datasets | Looking up what a `job.*` method takes, returns, or throws |
+| `switch-api/connection.md` | `Connection`: type, properties, file count | Routing to specific connections or reading connection properties |
+| `switch-api/http.md` | `HttpRequest` / `HttpResponse` + webhook pattern | Handling incoming HTTP webhooks |
+| `switch-api/enums.md` | All enums with string values (`LogLevel`, `AccessLevel`, `DatasetModel`, `Scope`, `Priority`, `Connection.Level`, etc.) | Looking up enum values |
+| `switch-api/document-classes.md` | `PdfDocument`, `PdfPage`, `ImageDocument`, `XmlDocument`, `XmpDocument`: read-only file introspection | Inspecting PDF, image, XML, or XMP file contents |
+| `switch-project/script-structure.md` | What files a script folder contains, `manifest.xml` format, how `SwitchVersion` selects the Node.js version and which tools overwrite it, Script vs App | Setting up a new script project, converting a Script to an App, or working out which Node.js version a script or app will run on |
+| `switch-project/tooling.md` | SwitchScriptTool commands and install paths, folder vs `.sscript` trade-offs, deployment | Running SwitchScriptTool: transpiling, packing, unpacking, or deploying |
+| `switch-project/debugging.md` | Enabling debug mode in Switch Designer, debuggable entry points, VS Code attach | Debugging a script |
+| `switch-project/vscode.md` | Type declarations, tsconfig for TypeScript 6, ESLint rules | Setting up VS Code or fixing type errors |
+| `switch-project/script-declaration.md` | XML declaration reference: properties, connections, execution config; agents may edit this file directly | Understanding, adding, or editing script properties/connections/execution config |
+| `switch-project/property-editors.md` | Property editor types, string return values, literal editors, dropdowns | Defining property editors in XML or reading property values in code |
+| `switch-api/job-patterns.md` | `Job` **rules and gotchas**: file access semantics, temp cleanup, which `sendTo*()` suits which connection type, dataset/child ordering, executor limits | Writing or reviewing job-handling code. Pair with `job.md` when you also need signatures |
+| `switch-api/execution-environment.md` | Execution modes (`Concurrent`/`Serialized`, `ExecutionGroup`, `NumberOfSlots`), process/concurrency model, state persistence across job invocations, unhandled-rejection behavior, npm/native module constraints | Choosing or changing an execution mode, relying on module-level state across jobs, handling errors/rejections, or using third-party npm packages |
+| `switch-api/logging.md` | Log level semantics, logging practice, `console.log` limitation, common gotchas | Adding or reviewing `job.log()`/`flowElement.log()`/`job.fail()`/`failProcess()` calls |
+| `switch-project/logs-and-dataroot.md` | Locating the Application Data Root, querying `ServerLogs.db3` directly | Diagnosing or validating a script from its actual log output rather than by reading the code |
+| `switch-appstore/app-guidelines.md` | Pre-publish checklist for Appstore apps: property naming/tooltips/editors, entry point and sendTo consistency, logging quality, packaging, and the app-only submission rules (localization, signed universal macOS binaries) | Preparing a script for publication as an app, or reviewing one against Appstore submission criteria |
+| `switch-project/property-documentation.md` | Writing guidance for `Tooltip` and `DetailedInfo` content on properties/connections | Writing or reviewing the text in a property's or connection's `Tooltip`/`DetailedInfo` |
+| `switch-appstore/app-store-listing.md` | Writing guidance for the declaration's Appstore listing fields: `Description`, `Compatibility`, `SupportInfo`, `AppDiscovery`, `Connections` | Writing or reviewing the app's Appstore listing text |
+| `switch-appstore/app-manual.md` | Writing guidance for the separate app manual document uploaded during Appstore review (`documentation-app_name.docx` template) | Preparing the app manual document for Appstore submission |
+| `switch-appstore/app-store-submission.md` | Writing guidance for the Create Appstore App / Create Appstore App Version web forms: Short Description, What's new, Eula, icon specs, and which fields reuse content already written elsewhere | Preparing content for the Appstore website submission forms |
+| `switch-api/api-versions.md` | Which Switch release added each scripting API class, method, and enum value; API availability follows the running Switch, not `manifest.xml` | 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 |
+<!-- docs-index:table end -->
 
 ## Key rules
+- Before scaffolding a new script or app, work through `switch-project/project-planning.md` with the user.
 - Always consult the API reference files above before writing or modifying script code.
-- Do not `export` entry point functions.
+- If the script or app must run on a Switch version older than the latest, check each API call
+  against `switch-api/api-versions.md`. The API files mark anything newer than the baseline with
+  "Switch X+" (a `// Switch X+` comment above a signature, or a note in the text), meaning that
+  version or later.
+- To find documented behavioural pitfalls before writing code in an area, grep the `switch-api/`,
+  `switch-project/`, and `switch-appstore/` folders alongside this file for `known issue`, `gotcha`,
+  `quirk`, `caveat` (case-insensitive) — every documented pitfall uses one of these four terms.
+- Do not `export` entry point functions. Declare them with the literal `function` keyword at top
+  level — arrow functions, `exports.name = ...`, and class methods are invisible to Switch.
+- Switch discovers entry points with a regex, not a parser. Never write a string literal whose
+  content ends with a backslash, a regex literal, or division outside the plain `word / word`
+  shape — each silently deletes a span of real code, and every entry point inside that span
+  disappears with no error anywhere. Read `switch-api/entry-points.md` §
+  Entry-point scanner constraints before editing `main.ts`/`main.js`.
 - Every `jobArrived` invocation must end with exactly one `job.sendTo*()` or `job.fail()` call — either in the same invocation or deferred to `timerFired` via job information stored in global data.
 - Use `AccessLevel.ReadOnly` for `job.get()` unless the file content will be modified.
 - Use VS Code snippets (`.vscode/switch.code-snippets`, prefix `switch…`) to scaffold entry points.
 - After calling `createJob()`, `createChild()`, or `createDataset()` with a file path, the script must delete the source file/folder after routing — Switch does not auto-remove it.
-- The XML declaration (`<ScriptID>.xml`) can be edited directly — read `switch-api/api-script-declaration.md` first and follow its rules exactly (no schema validates this format, so mistakes fail silently). Never change an existing script's `Name`. Bump `Version` on every declaration edit. Leave `manifest.xml` edits (package type, declaration filename, program files) to the user unless explicitly asked.
+- The XML declaration (`<ScriptID>.xml`) can be edited directly — read `switch-project/script-declaration.md` first and follow its rules exactly (no schema validates this format, so mistakes fail silently). Never change an existing script's `Name`. Bump `Version` on every declaration edit. Leave `manifest.xml` edits (package type, declaration filename, program files) to the user unless explicitly asked.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfocussw/switch-scripting-context",
-  "version": "25.11.0-beta.9",
+  "version": "25.11.1-beta.0",
   "description": "AI coding assistant context for Enfocus Switch scripting (Node.js/TypeScript)",
   "keywords": [
     "switch",
@@ -27,20 +27,24 @@
     "docs/",
     "!docs/superpowers",
     "!docs/temp",
+    "!docs/adr",
     "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "build:test": "tsc src/init.test.ts --outDir dist --target ES2020 --module commonjs --lib ES2020 --types node --strict --esModuleInterop --skipLibCheck",
-    "test": "npm run build && npm run build:test && node dist/init.test.js",
-    "prepack": "npm run build",
-    "postpack": "node -e \"const fs=require('fs');const version=process.env.npm_package_version;const scoped=process.env.npm_package_name.replace(/^@/,'').replace('/','-')+'-'+version+'.tgz';const unscoped=process.env.npm_package_name.replace(/^@[^/]+\\//,'')+'-'+version+'.tgz';if(scoped!==unscoped&&fs.existsSync(scoped))fs.renameSync(scoped,unscoped);\""
+    "test": "npm run build && npm run build:test && node dist/init.test.js && node scripts/check-prose.js && node scripts/check-gotcha-tags.js && node scripts/generate-docs-index.js --check",
+    "prepack": "npm run build && node scripts/readme-links.js --publish",
+    "postpack": "node scripts/readme-links.js --restore && node -e \"const fs=require('fs');const version=process.env.npm_package_version;const scoped=process.env.npm_package_name.replace(/^@/,'').replace('/','-')+'-'+version+'.tgz';const unscoped=process.env.npm_package_name.replace(/^@[^/]+\\//,'')+'-'+version+'.tgz';if(scoped!==unscoped&&fs.existsSync(scoped))fs.renameSync(scoped,unscoped);\"",
+    "lint:prose": "node scripts/check-prose.js",
+    "lint:gotchas": "node scripts/check-gotcha-tags.js",
+    "docs:generate": "node scripts/generate-docs-index.js"
   },
   "author": "Sam Wallace",
   "license": "ISC",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/samw_pacol/switch-scripting-context.git"
+    "url": "git+https://github.com/esko-bv/enf-switch-scripting-context.git"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -50,9 +54,9 @@
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0"
   },
-  "homepage": "https://github.com/samw_pacol/switch-scripting-context#readme",
+  "homepage": "https://github.com/esko-bv/enf-switch-scripting-context#readme",
   "bugs": {
-    "url": "https://github.com/samw_pacol/switch-scripting-context/issues"
+    "url": "https://github.com/esko-bv/enf-switch-scripting-context/issues"
   },
   "engines": {
     "node": ">=18"

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

@@ -1,63 +0,0 @@
-# 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
-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 [api-script-declaration.md](api-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.
-
-```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.
-
-## File count
-
-```ts
-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()` for traffic light connections.
-
-| Value | String |
-|---|---|
-| `Connection.Level.Success` | `"success"` |
-| `Connection.Level.Warning` | `"warning"` |
-| `Connection.Level.Error` | `"error"` |
-
-Available as `EnfocusSwitch.Connection.Level.*` outside `main.ts`.

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

@@ -1,82 +0,0 @@
-# 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.
-
-## 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.
-
-## 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.
-
-```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()`. Maximum execution: 60 seconds, after which the script executor is killed. Applies to: `jobArrived`, `timerFired`, `httpRequestTriggeredSync`, `httpRequestTriggeredAsync`, `flowStartTriggered`, `flowStopTriggered`.
-
-## Webhooks
-
-```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.
-
-```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.
-
-```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.
-
-```ts
-async function validateConnectionProperties(s: Switch, flowElement: FlowElement, c: Connection, tags: string[]): Promise<{ tag: string, valid: boolean }[]>
-```
-Validates one or more connection property values.
-
-```ts
-async function findExternalEditorPath(s: Switch, flowElement: FlowElement, tag: string): Promise<string>
-```
-Resolves the path to an external editor for a property.

package/docs/switch-api/api-job-patterns.md

@@ -1,79 +0,0 @@
-# Job Patterns and Behavioral Rules
-
-Common behavioral rules for file access, routing, temp file cleanup, and child jobs. These are the most frequent sources of bugs.
-
----
-
-## File access semantics
-
-`job.get(accessLevel)` and `job.getDataset(name, accessLevel)` behave differently depending on the access level:
-
-| Access level | What it returns | Modification |
-|---|---|---|
-| `AccessLevel.ReadOnly` | Path in the element's **input folder** | Throws if the file is modified |
-| `AccessLevel.ReadWrite` | Path in a **temp location** (copy) | Auto-uploaded to the output folder when `sendTo*()` is called |
-
-Always use `AccessLevel.ReadOnly` unless you need to modify the file content.
-
----
-
-## Temp file cleanup
-
-Switch does **not** automatically clean up files you create or pass to job-creation methods. The script is responsible:
-
-- Files/folders passed to `flowElement.createJob(path)` — delete after routing.
-- Files/folders passed to `job.createChild(path)` — delete after routing.
-- Files/folders passed to `job.createDataset(name, filePath, model)` — delete after routing.
-
-> Files accumulate between executor refreshes if not cleaned up. The executor is refreshed after 5 min idle, 5,000 tasks, 150 MB memory, or 1,024 open file handles — at which point accumulated files are removed automatically, but do not rely on this.
-
----
-
-## Sending jobs
-
-After calling any `job.sendTo*()`:
-- Only further `sendTo*()` calls and `job.fail()` are allowed on that job object.
-- An **unmodified** incoming job can be sent to multiple connections (call `sendTo*()` multiple times).
-- A **modified** job (ReadWrite access used) must use `job.createChild()` to produce additional copies for routing to other connections.
-
-```ts
-// Route unmodified job to two connections — OK
-await job.sendToData(Connection.Level.Success);
-await job.sendToData(Connection.Level.Warning); // only if job was not modified
-
-// Route modified content to multiple connections — use createChild
-const child = await job.createChild(tempPath);
-await job.sendTo(conn1);
-await child.sendTo(conn2);
-// Clean up tempPath after routing
-await fs.promises.rm(tempPath);
-```
-
----
-
-## processLater
-
-`job.processLater()` defers the job for the next `timerFired` invocation.
-
-Constraints:
-- Minimum deferral: **10 seconds** from the time `jobArrived` was called.
-- Cannot be called on jobs created with `createJob()` or `createChild()`.
-- Private data changes made before `processLater()` are preserved.
-- New datasets created before `processLater()` are **discarded**.
-
----
-
-## Executor cleanup thresholds
-
-The Node.js executor process is recycled when any of the following thresholds is reached:
-
-| Threshold | Value |
-|---|---|
-| Idle time | 5 minutes |
-| Tasks processed | 5,000 |
-| Memory consumption | 150 MB |
-| Open file handles | 1,024 |
-
-On cleanup, any files/folders created in the temp area are removed. Always close file handles and database connections before the entry point returns.
-
-See [api-execution-environment.md](api-execution-environment.md) for how this process model affects state persistence and error handling across job invocations.

package/docs/switch-api/api-script-structure.md

@@ -1,85 +0,0 @@
-# Script Project Structure
-
-A Switch script project lives in a **script folder** during development and is distributed as a `.sscript` package (ZIP).
-
-> **Agent editing policy**: Edit TypeScript/JavaScript source files (`main.ts`, `main.js`) and the XML declaration (`<ScriptID>.xml`) freely — see [api-script-declaration.md](api-script-declaration.md) for the declaration's rules. Leave `manifest.xml` to the user unless explicitly asked.
-
-## Script folder files
-
-| File | Required | Notes |
-|---|---|---|
-| `manifest.xml` | Yes | Switch internal use only. Do not edit manually. |
-| `<ScriptID>.xml` | Yes | Script declaration (properties, connections, execution config). See [api-script-declaration.md](api-script-declaration.md). |
-| `main.ts` | Yes (TypeScript) | Source file. Edit this. |
-| `main.js` | Yes | Compiled output executed by Switch. Generated by transpiling `main.ts`. |
-| `main.js.map` | No | Source map, generated alongside `main.js`. |
-| `package.json` | Yes (TypeScript) | NPM config for type declarations. |
-| `tsconfig.json` | Yes (TypeScript) | TypeScript transpilation options. |
-| `<IconFileName>.png` | No | 32×32 px, RGB, not interlaced. Extension must be `.png`. |
-| `node_modules/` | No | Local npm packages. |
-| `Resources/` | No | Extra resource files bundled when packing with SwitchScriptTool. |
-| `<LanguageCode>.ts` | No | Translation files (Switch App SDK). |
-| `.vscode/launch.json` | No | Debug config (created by SwitchScriptTool). |
-| `.vscode/switch.code-snippets` | No | Entry point snippets (TypeScript only). |
-
-> After editing `main.ts`, transpile with SwitchScriptTool to regenerate `main.js` before testing in Switch.
-
-## manifest.xml format
-
-```xml
-<Manifest>
-    <ScripterInstanceName>myScript</ScripterInstanceName>
-    <SwitchVersion>24.0</SwitchVersion>
-    <ScriptPackageFormatVersion>1.0</ScriptPackageFormatVersion>
-    <ScriptPasswordProtected>No</ScriptPasswordProtected>
-    <ScriptPackageType>Script</ScriptPackageType>
-    <ScriptDeclarationFile>myScript.xml</ScriptDeclarationFile>
-    <ScriptProgramFiles>
-        <ScriptProgramFile ScriptLanguage="NodeJSScript">main.ts</ScriptProgramFile>
-    </ScriptProgramFiles>
-    <ScriptIconFile>myScript_32.png</ScriptIconFile>
-    <LocalizationItems/>
-</Manifest>
-```
-
-`ScriptPackageType` is either `Script` (regular) or `App` (scripted plug-in).
-
-## Node.js version per Switch version
-
-`SwitchVersion` in `manifest.xml` determines which Node.js version executes the script — Switch uses the **latest** Node.js version bundled with the Switch release that created the script.
-
-| Switch version | `SwitchVersion` | Node.js used |
-|---|---|---|
-| Switch 2020 Spring | `20.0` | 12 |
-| Switch 2020 Fall | `20.1` | 12 |
-| Switch 2021 Spring | `21.0` | 14 |
-| Switch 2021 Fall | `21.1` | 16 |
-| Switch 2022 Spring | `22.0` | 16 |
-| Switch 2022 Fall | `22.1` | 16 |
-| Switch 2023 Fall | `23.1` | 18 |
-| Switch 2024 Spring | `24.0` | 18 |
-| Switch 2024 Fall | `24.1` | 20 |
-| Switch 25.11 | `25.11` | 20 |
-
-> **Mac (Apple Silicon):** For scripts created in Switch 2021 Fall or later, Switch runs the native ARM build of Node.js on Apple Silicon. Scripts created in earlier versions run under Rosetta using the Intel Node.js build. If a script bundles platform-specific binaries, ship both Intel and ARM variants.
-
-## Script vs App
-
-| | Script | App |
-|---|---|---|
-| `ScriptPackageType` | `Script` | `App` |
-| Appears in Elements pane | No (used via Script element) | Yes, as its own element |
-| Distribution | Freely | Enfocus Appstore only |
-| Position in pane | — | Configured via `PositionInElementPane` in XML |
-
-## Execution modes
-
-Set in the XML declaration via SwitchScripter. 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.
-
-**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.
-
-See [api-execution-environment.md](api-execution-environment.md#two-independent-concurrency-tiers) — neither `NumberOfSlots` nor execution group maps to a count of Node.js OS processes; they gate job dispatch on the Switch Server, separate from the pooled executor processes that actually run script code.