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

package/dist/init.js

@@ -33,6 +33,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRoutingTable = parseRoutingTable;
+exports.apiFiles = apiFiles;
 exports.generateAgentsMd = generateAgentsMd;
 exports.generateGeminiMd = generateGeminiMd;
 exports.generateWindsurfRules = generateWindsurfRules;
@@ -47,6 +49,46 @@ const readline = __importStar(require("readline"));
 // ─── Markers ─────────────────────────────────────────────────────────────────
 const MARKER_BEGIN = '<!-- switch-scripting-context begin -->';
 const MARKER_END = '<!-- switch-scripting-context end -->';
+// ─── Shared content (single source of truth for all generated tool files) ────
+/** Package root, whether running from src/ (ts-node) or dist/. */
+function packageRoot() {
+    return path.resolve(__dirname, '..');
+}
+/**
+ * The routing table in docs/switch-scripting.md is the single source of truth for
+ * which API docs exist and when to load each one. Everything the CLI generates is
+ * derived from it, so a new doc file needs registering in exactly one place here
+ * (plus README.md, which init.test.ts checks).
+ */
+function parseRoutingTable(root = packageRoot()) {
+    const hub = fs.readFileSync(path.join(root, 'docs', 'switch-scripting.md'), 'utf8');
+    const docs = [];
+    for (const line of hub.split('\n')) {
+        // | `<switch-api|switch-project|switch-appstore>/<file>.md` | <contents> | <load when> |
+        const m = /^\|\s*`(switch-api|switch-project|switch-appstore)\/([a-z0-9-]+\.md)`\s*\|(.*)\|(.*)\|\s*$/.exec(line);
+        if (m)
+            docs.push({ file: `${m[1]}/${m[2]}`, loadWhen: m[4].trim() });
+    }
+    if (docs.length === 0) {
+        throw new Error('No API docs found in docs/switch-scripting.md — the routing table format changed. ' +
+            'Generated tool config would be empty; fix parseRoutingTable() before publishing.');
+    }
+    return docs;
+}
+/** Filenames only, in routing-table order. */
+function apiFiles(root) {
+    return parseRoutingTable(root).map(d => d.file);
+}
+const INLINE_CORE_RULES = `## Core rules
+
+- Entry point functions are top-level async functions — do NOT use \`export\`, arrow functions, or class methods; declare them with the literal \`function\` keyword.
+- Switch finds 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 the entry points inside it, with no error. Read \`entry-points.md\` § Entry-point scanner constraints before editing \`main.ts\`/\`main.js\`.
+- Every \`jobArrived\` must end with exactly one \`job.sendTo*()\` or \`job.fail()\`.
+- Use \`AccessLevel.ReadOnly\` for \`job.get()\` unless the file content will be modified.
+- After \`createJob()\`, \`createChild()\`, or \`createDataset()\` with a file path, delete the source file after routing — Switch does not auto-remove it.
+- The XML declaration (\`<ScriptID>.xml\`) can be edited directly — read \`script-declaration.md\` first and follow its rules exactly (nothing validates this format, so mistakes fail silently). Never change an existing script's \`Name\`; bump \`Version\` on every declaration edit. Leave \`manifest.xml\` to the user unless explicitly asked.
+- After editing \`main.ts\`, transpile with \`SwitchScriptTool --transpile <folder>\` — do not use \`tsc\` directly.
+- Never use a script folder in production — pack with \`SwitchScriptTool --pack\` first; folders are excluded from flow exports.`;
 // ─── Content generators ──────────────────────────────────────────────────────
 function generateClaudeMd(docsDir) {
     return `${MARKER_BEGIN}
@@ -76,27 +118,6 @@ You are working on an Enfocus Switch scripting project (Node.js/TypeScript).
 ${MARKER_END}`;
 }
 function generateCursorMdc(docsDir) {
-    const apiFiles = [
-        'api-entry-points.md',
-        'api-job.md',
-        'api-flow-element.md',
-        'api-connection.md',
-        'api-http.md',
-        'api-enums.md',
-        'api-document-classes.md',
-        'api-script-declaration.md',
-        'api-script-structure.md',
-        'api-tooling.md',
-        'api-debugging.md',
-        'api-vscode.md',
-        'api-property-editors.md',
-        'api-job-patterns.md',
-        'api-switch.md',
-        'api-execution-environment.md',
-        'api-logging.md',
-        'api-logs-and-dataroot.md',
-    ];
-    const fileList = apiFiles.map(f => `- \`${docsDir}/switch-api/${f}\``).join('\n');
     return `---
 description: Enfocus Switch scripting rules and API reference for Node.js/TypeScript scripts
 globs: ["**/*.ts", "**/*.js"]
@@ -106,55 +127,21 @@ alwaysApply: false
 ${MARKER_BEGIN}
 You are working on an Enfocus Switch scripting project (Node.js/TypeScript).
 
-## Core rules
-
-- Entry point functions are top-level async functions — do NOT use \`export\`.
-- Every \`jobArrived\` must end with exactly one \`job.sendTo*()\` or \`job.fail()\`.
-- Use \`AccessLevel.ReadOnly\` for \`job.get()\` unless the file content will be modified.
-- After \`createJob()\`, \`createChild()\`, or \`createDataset()\` with a file path, delete the source file after routing — Switch does not auto-remove it.
-- Never edit \`<ScriptID>.xml\` or \`manifest.xml\` directly. For property/connection changes, instruct the user to use SwitchScripter.
-- After editing \`main.ts\`, transpile with \`SwitchScriptTool --transpile <folder>\` — do not use \`tsc\` directly.
-- Never use a script folder in production — pack with \`SwitchScriptTool --pack\` first; folders are excluded from flow exports.
+${INLINE_CORE_RULES}
 
 ## API reference
 
-Read \`${docsDir}/switch-scripting.md\` for the full index, then consult the relevant file:
+Load the file matching the task below. \`${docsDir}/switch-scripting.md\` has the same index plus
+the project-wide key rules:
 
-${fileList}
+${inlineApiFileList(docsDir)}
 ${MARKER_END}`;
 }
-// ─── Shared inline content (for tools without @file import support) ──────────
-const INLINE_CORE_RULES = `## Core rules
-
-- Entry point functions are top-level async functions — do NOT use \`export\`.
-- Every \`jobArrived\` must end with exactly one \`job.sendTo*()\` or \`job.fail()\`.
-- Use \`AccessLevel.ReadOnly\` for \`job.get()\` unless the file content will be modified.
-- After \`createJob()\`, \`createChild()\`, or \`createDataset()\` with a file path, delete the source file after routing — Switch does not auto-remove it.
-- Never edit \`<ScriptID>.xml\` or \`manifest.xml\` directly. For property/connection changes, instruct the user to use SwitchScripter.
-- After editing \`main.ts\`, transpile with \`SwitchScriptTool --transpile <folder>\` — do not use \`tsc\` directly.
-- Never use a script folder in production — pack with \`SwitchScriptTool --pack\` first; folders are excluded from flow exports.`;
-const API_FILES = [
-    'api-entry-points.md',
-    'api-job.md',
-    'api-flow-element.md',
-    'api-connection.md',
-    'api-http.md',
-    'api-enums.md',
-    'api-document-classes.md',
-    'api-script-declaration.md',
-    'api-script-structure.md',
-    'api-tooling.md',
-    'api-debugging.md',
-    'api-vscode.md',
-    'api-property-editors.md',
-    'api-job-patterns.md',
-    'api-switch.md',
-    'api-execution-environment.md',
-    'api-logging.md',
-    'api-logs-and-dataroot.md',
-];
+// ─── Inline block (for tools without @file import support) ──────────────────
 function inlineApiFileList(docsDir) {
-    return API_FILES.map(f => `- \`${docsDir}/switch-api/${f}\``).join('\n');
+    return parseRoutingTable()
+        .map(d => `- \`${docsDir}/${d.file}\` — ${d.loadWhen}`)
+        .join('\n');
 }
 function generateInlineBlock(docsDir) {
     return `You are working on an Enfocus Switch scripting project (Node.js/TypeScript).
@@ -163,7 +150,8 @@ ${INLINE_CORE_RULES}
 
 ## API reference
 
-Read \`${docsDir}/switch-scripting.md\` for the full index, then consult the relevant file:
+Load the file matching the task below. \`${docsDir}/switch-scripting.md\` has the same index plus
+the project-wide key rules:
 
 ${inlineApiFileList(docsDir)}`;
 }
@@ -345,13 +333,36 @@ function applyFileAction(action, dryRun) {
     console.log(`  ${rel} → ${label}`);
 }
 // ─── Docs copy ────────────────────────────────────────────────────────────────
+/** Paths under docs/ that are never shipped to a consuming project. */
+const DOCS_EXCLUDE = ['superpowers', 'temp'];
 function copyDocs(packageRoot, destDir, dryRun) {
     const src = path.join(packageRoot, 'docs');
+    const rel = path.relative(process.cwd(), destDir);
     if (dryRun) {
-        console.log(`  [dry-run] Copying docs/ → ${path.relative(process.cwd(), destDir)}/`);
+        if (fs.existsSync(destDir)) {
+            console.log(`  [dry-run] ${rel}/ → wiped (removes files from a previous version, e.g. after a doc was renamed or moved)`);
+        }
+        console.log(`  [dry-run] Copying docs/ → ${rel}/`);
         return;
     }
-    fs.cpSync(src, destDir, { recursive: true });
+    // destDir is entirely owned by this tool (see the .gitignore comment it writes), so wiping
+    // it first is safe. Without this, a doc renamed or moved between versions (e.g. a docs/
+    // folder restructuring) would leave the old file behind forever: cpSync only adds/overwrites,
+    // it never removes, and destDir is gitignored so nothing would surface the staleness.
+    if (fs.existsSync(destDir)) {
+        fs.rmSync(destDir, { recursive: true, force: true });
+    }
+    // The published tarball already omits these, but init may run from a git clone.
+    fs.cpSync(src, destDir, {
+        recursive: true,
+        filter: (from) => {
+            const rel = path.relative(src, from);
+            if (!rel)
+                return true;
+            const [top] = rel.split(path.sep);
+            return !DOCS_EXCLUDE.includes(top) && path.basename(from) !== '.DS_Store';
+        },
+    });
     console.log(`  docs → ${path.relative(process.cwd(), destDir)}/`);
 }
 // ─── .gitignore update ───────────────────────────────────────────────────────
@@ -370,20 +381,46 @@ function updateGitignore(targetRoot, docsDir, dryRun) {
     fs.appendFileSync(gitignorePath, entry, 'utf8');
     console.log(`  .gitignore → appended ${docsDir}/ entry`);
 }
-/** All AI config file paths that init may have created. */
-function aiConfigPaths(targetRoot, docsDir) {
-    return TOOL_REGISTRY.flatMap(t => t.files.map(f => f.targetPath(targetRoot, docsDir)));
+/** AI config files that init may have created, for all tools or only the given tool ids. */
+function aiConfigFiles(targetRoot, docsDir, tools) {
+    return TOOL_REGISTRY
+        .filter(t => !tools || tools.includes(t.id))
+        .flatMap(t => t.files.map(file => ({ filePath: file.targetPath(targetRoot, docsDir), file })));
+}
+/** The frontmatter a generator writes above the marker, trimmed; empty if it writes none. */
+function generatedFrontmatter(file, docsDir) {
+    const generated = file.generate(docsDir);
+    return generated.slice(0, generated.indexOf(MARKER_BEGIN)).trim();
 }
-function removeAiConfig(filePath, dryRun) {
+/** Deletes now-empty folders from dir upwards, stopping at targetRoot. */
+function removeEmptyDirs(dir, targetRoot) {
+    while (dir !== targetRoot && dir.startsWith(targetRoot + path.sep) && fs.readdirSync(dir).length === 0) {
+        fs.rmdirSync(dir);
+        dir = path.dirname(dir);
+    }
+}
+function removeAiConfig(filePath, file, docsDir, targetRoot, dryRun) {
     if (!fs.existsSync(filePath))
         return;
-    const content = fs.readFileSync(filePath, 'utf8');
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const eol = raw.includes('\r\n') ? '\r\n' : '\n';
+    const content = raw.replace(/\r\n/g, '\n');
     const range = findMarkerRange(content);
     if (!range)
         return; // nothing from us in this file
     const rel = path.relative(process.cwd(), filePath);
-    const before = content.slice(0, range[0]).trim();
+    let before = content.slice(0, range[0]).trim();
     const after = content.slice(range[1]).trim();
+    // Copilot scoped instructions and Cursor .mdc put frontmatter above the marker. Only an exact
+    // copy of what the generator writes counts as ours; edited or user-written frontmatter stays.
+    const ours = generatedFrontmatter(file, docsDir);
+    if (ours && before === ours) {
+        before = '';
+    }
+    else if (ours && before.endsWith('\n' + ours)) {
+        // init appended our block, frontmatter included, below the user's own content
+        before = before.slice(0, -ours.length).trim();
+    }
     if (!before && !after) {
         // File is entirely our content — delete it
         if (dryRun) {
@@ -391,6 +428,7 @@ function removeAiConfig(filePath, dryRun) {
             return;
         }
         fs.unlinkSync(filePath);
+        removeEmptyDirs(path.dirname(filePath), targetRoot);
         console.log(`  ${rel} → deleted`);
     }
     else {
@@ -400,7 +438,7 @@ function removeAiConfig(filePath, dryRun) {
             console.log(`  [dry-run] ${rel} → removed Switch section`);
             return;
         }
-        fs.writeFileSync(filePath, stripped, 'utf8');
+        fs.writeFileSync(filePath, stripped.replace(/\n/g, eol), 'utf8');
         console.log(`  ${rel} → removed Switch section`);
     }
 }
@@ -427,6 +465,18 @@ function remove(options) {
     const docsDestDir = path.join(targetRoot, options.docsDir);
     if (options.dryRun)
         console.log('\nDry run — no files will be written.\n');
+    const tools = options.tools;
+    const partial = tools && !TOOL_REGISTRY.every(t => tools.includes(t.id));
+    if (partial) {
+        // Removing some tools leaves the rest configured, and they still reference the docs folder.
+        // Listing every tool leaves nothing referencing it, so that falls through to a full remove.
+        console.log('Cleaning AI config files...');
+        for (const { filePath, file } of aiConfigFiles(targetRoot, options.docsDir, options.tools)) {
+            removeAiConfig(filePath, file, options.docsDir, targetRoot, options.dryRun);
+        }
+        console.log('\nDone.\n');
+        return;
+    }
     // 1. Remove docs dir
     console.log('Removing docs...');
     if (fs.existsSync(docsDestDir)) {
@@ -443,8 +493,8 @@ function remove(options) {
     }
     // 2. Remove AI config sections / files
     console.log('\nCleaning AI config files...');
-    for (const filePath of aiConfigPaths(targetRoot, options.docsDir)) {
-        removeAiConfig(filePath, options.dryRun);
+    for (const { filePath, file } of aiConfigFiles(targetRoot, options.docsDir)) {
+        removeAiConfig(filePath, file, options.docsDir, targetRoot, options.dryRun);
     }
     // 3. Update .gitignore
     console.log('\nUpdating .gitignore...');
@@ -519,6 +569,7 @@ function parseArgs(argv) {
                 process.exit(1);
             }
             initOptions.tools = raw.map(t => idMap.get(t));
+            removeOptions.tools = initOptions.tools;
             toolsExplicit = true;
         }
         else if (arg === '--docs-dir' && args[i + 1]) {
@@ -569,7 +620,7 @@ Usage: switch-scripting-context <command> [options]
 
 Commands:
   init      Copy docs and generate AI context config files
-  remove    Remove all files and config added by init
+  remove    Remove files and config added by init (all of it, or only some tools' config)
 
 Options (init):
   --tools <list>    Comma-separated tools to configure
@@ -582,6 +633,8 @@ Options (init):
   --help            Show this help message
 
 Options (remove):
+  --tools <list>    Only remove these tools' config; keeps the docs folder and other tools
+                    Default: remove everything, same as listing every tool
   --docs-dir <dir>  Docs folder to remove (default: switch-docs)
   --dry-run         Print what would happen without writing any files
 
@@ -591,6 +644,7 @@ Examples:
   npx switch-scripting-context init --docs-dir ai-docs --dry-run
   npx switch-scripting-context remove
   npx switch-scripting-context remove --dry-run
+  npx switch-scripting-context remove --tools cursor
 `);
 }
 // ─── Entry point ─────────────────────────────────────────────────────────────

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.
 
 ---