@enfocussw/switch-scripting-context 0.1.0

package/docs/switch-project/script-declaration.md

@@ -0,0 +1,407 @@
+---
+id: script-declaration
+category: switch-project
+order: 14
+summary: "XML declaration reference: properties, connections, execution config; agents may edit this file directly"
+triggers:
+  - "Understanding, adding, or editing script properties/connections/execution config"
+---
+
+# Script Declaration (XML)
+
+The file `<ScriptID>.xml` defines the script's metadata, custom properties, connection properties,
+and execution configuration. It is normally written by **SwitchScripter**, but the format is fully
+documented below — you can edit it directly.
+
+<!-- docs-index:contents begin -->
+## Contents
+
+- Agent editing policy
+- XML structure overview
+- Built-in ElementFields
+- Custom property elements (ElementFields)
+- ConnectionFields
+- ExtraProperties
+- Type reference
+- Escaped `ValueDescription` payloads
+- Reserved tag names
+- Annotated example
+<!-- docs-index:contents end -->
+
+## Agent editing policy
+
+- Editing this file directly is safe as long as you follow the rules on this page exactly — the
+  format has no schema, so Switch will silently misbehave (not error) on a malformed attribute.
+- Preserve every attribute you don't intend to change. Don't reformat, reorder attributes, or drop
+  fields you don't understand.
+- `Name` is the script's stable ID — never change it on an existing script (it's used as the flow
+  element type and referenced by installed flows). `DisplayName`, tooltips, defaults, adding/removing
+  custom properties, and connection topology are all safe to change directly.
+- `Version` identifies a released build, not an edit. Bump it only when the current value has
+  already been released (installed on a customer's or production Switch, or published on the
+  Appstore). If the current value was never released, keep editing under it; don't bump per
+  change. See the `Version` row below for format and what Switch does with it.
+- Custom property tag names must match `^[A-Za-z][A-Za-z0-9]*$`, must not start with `xml`
+  (case-insensitive), and must not collide with a [reserved tag](#reserved-tag-names) below. Switch
+  does **not** sanitize or rewrite bad tag names on load — it just fails to work correctly.
+- `manifest.xml` (declares the package's program file(s) and type) rarely needs edits; treat it as
+  low-risk to read but confirm with the user before changing `ScriptPackageType`,
+  `ScriptDeclarationFile`, or `ScriptProgramFiles`.
+- Never add or edit `ApplicationPath` or `ApplicationLicense` — these are app-only properties that
+  point Switch at a third-party application's install location and license. They must be set by the
+  user from the Switch Scripter GUI after the script package has been packed; Switch silently drops
+  them if written into the declaration file directly.
+- **Gotcha: reload the script element after changing properties.** When the declaration of a script
+  that is already used in a flow gains a property or a property changes, right-click the element in
+  Switch Designer and choose "Reload script" before activating the flow. Until then the element
+  keeps the old declaration: a new property doesn't appear in the element, and
+  `getPropertyStringValue()` on it throws `"Invalid tag: <tag>"`. Seen with a script folder on
+  Switch 26.07.
+
+---
+
+## XML structure overview
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Object>
+    <ElementFields>     <!-- required: built-in fields + custom property elements -->
+    <ConnectionFields>  <!-- optional: custom outgoing-connection property elements -->
+    <ExtraProperties>   <!-- optional: OAuth 2.0 editor config only -->
+</Object>
+```
+
+`ElementFields` is required — Switch rejects the whole declaration without it. `ConnectionFields`
+and `ExtraProperties` may be omitted or left empty.
+
+---
+
+## Built-in ElementFields
+
+These configure the flow element (name, topology, execution, pane placement, docs). All carry
+`Editor="hide"` and are never shown to the user directly. Add `Type="..."` to a field only when the
+value is non-string (see the table); an empty string field can omit `Type`.
+
+| Element | Values | Notes |
+|---|---|---|
+| `Name` | string | Stable script ID — **never change on an existing script**. Becomes the flow element `Type`. |
+| `DisplayName` | string | Shown in Switch. Empty falls back to `Name`. A `~` splits "Vendor~Element" — Switch shows the part after `~` as the short name and the whole string (space-joined) as the full name. |
+| `Version` | number | Format `[1-9][0-9]*(\.(0\|[1-9][0-9]*))*`, e.g. `1`, `2.1`. SwitchScripter accepts a whole number only for a script and at most one minor level for an app (`2.1`); it resets anything else. Bump once per release, not per edit (see [Agent editing policy](#agent-editing-policy)). Each flow records the version of the element it uses; Switch compares that recorded value with `UpgradeMaximumVersion` to decide whether to show `FlowUpgradeWarning`. |
+| `Keywords` | string | Space/comma/semicolon-separated. Elements pane search. |
+| `Tooltip` | string | Elements pane tooltip. |
+| `IncomingConnections` | `Yes` \| `No` | Add `RequireAtLeastOne="Yes"` when `Yes`. When `Yes`, the script must implement `jobArrived` (optionally `timerFired` too); when `No`, it must implement `timerFired` instead — see [entry-points.md](../switch-api/entry-points.md#job-processing). Setting `IncomingConnections="Yes" RequireAtLeastOne="No"` makes the incoming connection optional per instance: some instances can have zero incoming connections (e.g. a flow-starting webhook trigger) and others one wired in (e.g. a mid-flow processing step), with the script branching on both cases at runtime, typically gated by a property such as a mode enum. Confirmed working in Switch Designer. |
+| `OutgoingConnections` | `No` \| `One` \| `Unlimited` | Add `RequireAtLeastOne="Yes"` when `One`/`Unlimited`. `One` with `RequireAtLeastOne="No"` makes the outgoing connection optional: a flow with an instance that had no outgoing connection validated and activated (Switch 26.07). Always carries `DetailedInfo=""` (or a prose description of the connections, for generated docs). When not `No`, the script must call a `sendTo*()` method at least once for any job it actually routes (a purely timer/event-driven script that never touches a job — polling an API, rotating logs, etc. — is a legitimate exception); when `Unlimited`, never use `job.sendToSingle()` — see [job-patterns.md § Sending jobs](../switch-api/job-patterns.md#sending-jobs). |
+| `ConnectionType` | `Move` \| `Filter` \| `TrafficLight` | Governs which `ConnectionFields` children are legal — see [ConnectionFields](#connectionfields). |
+| `FunctionsNodeJSScript` | `;`-separated names | Entry point function names found in the script. Omit the element entirely if there is no Node.js program. |
+| `ExecutionMode` | `Concurrent` \| `Serialized` | |
+| `NumberOfSlots` | `Default` \| integer | Only meaningful when `Concurrent`. |
+| `ExecutionGroup` | string | Only meaningful when `Serialized`. Empty falls back to `Name`. |
+| `PerformanceTuning` | `Yes` \| `No` | When `Yes`, `IdleAfterJob` (and `NumberOfSlots` if concurrent) become visible/editable in Switch. |
+| `IdleAfterJob` | number (seconds) | |
+| `PositionInElementPane` | `Basics` \| `Tools` \| `Communication` \| `Apps` \| `Configurators` \| `Metadata` \| `Database` | Which section of the Elements pane the script appears under. |
+| `SubcategoryInElementPane` | escaped XML, see [§ escaped payloads](#escaped-valuedescription-payloads) | Apps/Configurators only. |
+| `DispositionInElementPane` | numeric string or empty | Sort position within the category. Empty = alphabetical. |
+| `Description` | string | Long description. |
+| `Compatibility` | string | Configurator only: third-party app compatibility notes. |
+| `SupportInfo` | string | Configurator only: support email/URL. |
+| `AppDiscovery` | string | Configurator only: how the app is located on disk. |
+| `FlowUpgradeWarning` | string | Warning shown during flow upgrade. |
+| `UpgradeMaximumVersion` | number | Previous version up to which the upgrade warning is shown. Optional. |
+| `Connections` | string | Prose description of outgoing connections, for generated docs. |
+| `SwitchModule` | `Configurator` \| `Metadata` \| `Scripting` \| `Database` \| `SwitchClient` \| `SwitchClientSDK` | Licensing module. |
+| `ObsoleteProperties` | `;`/`,`/whitespace-separated tag names | Suppresses "unknown property" warnings when a flow already has properties you removed. Add old tag names here when removing a custom property. |
+| `ObsoleteConnectionProperties` | same | Same, for removed connection properties. |
+
+Do **not** add `ApplicationPath` or `ApplicationLicense` as element names — Switch silently drops
+them. These app-only properties must be configured by the user from the Switch Scripter GUI after
+the package is packed, not written into the declaration file.
+
+---
+
+## Custom property elements (ElementFields)
+
+Each user-defined property is a child element of `<ElementFields>` with `UserDefined="true"`. The
+element name is the property's **tag** (used as the `tag` argument in `getPropertyStringValue()`)
+and must follow the [tag name rules](#reserved-tag-names).
+
+The element must **never be self-closing**. Its text content holds the property's *current value*
+— e.g. `<Count ...>8</Count>`, not `<Count ... Default="8" />`. A self-closing custom property is
+non-editable in Switch Designer.
+
+```xml
+<MyProperty UserDefined="true" Type="string" Editor="choosefolder" LocalizedTagName="My Property"
+            Tooltip="Select the output folder" DetailedInfo="" Validation="Standard" Default=""
+            Subtype="">Default value goes here</MyProperty>
+```
+
+Key attributes:
+
+| Attribute | Description |
+|---|---|
+| `UserDefined` | Always `"true"` for custom properties. |
+| `Type` | Value type discriminator — see [Type reference](#type-reference). |
+| `Editor` | `;`-joined chain of editor tokens (inline editor first, then modal editors) — see [property-editors.md](property-editors.md). |
+| `Subtype` | Which editor in the `Editor` chain is currently active for the stored value. For a single-editor property this equals that editor's token (e.g. `"inline"`); for a bare modal editor with no inline component, leave it `""`. Exception: `Type="password"` takes `Subtype=""` even though `Editor="inline"` alone — see [property-editors.md](property-editors.md#common-practices). This attribute is read by Switch's validator at runtime, not just bookkeeping — keep it consistent with `Editor`. |
+| `LocalizedTagName` | Display name shown in the Properties pane. **App guideline (mandatory for apps, recommended for scripts):** 30 characters max, sentence-style capitalization (`"Customer name"`, not `"Customer Name"`). |
+| `Tooltip` | Tooltip shown in the Properties pane. **App guideline (mandatory for apps, recommended for scripts):** give every property a tooltip. The only exception is a property that's fully self-explanatory from its name alone with no extra constraints (e.g. "Number of copies" with no min/max) — if there's anything a user would need to know (units, valid range, format, an example value), put it in the tooltip. |
+| `DetailedInfo` | Long-form description for generated docs. Always include the attribute (empty string `""` is fine) — omitting it makes the property non-editable in Switch Designer. |
+| `Validation` | `None` (skip validation) \| `Standard` (built-in validator) \| `Custom` (needs a `validateProperties` entry point) \| `Standard and custom` (both, custom only runs if standard passes). If any property uses `Custom` or `Standard and custom`, the script must implement `validateProperties` (or `validateConnectionProperties` for a connection field) — see [entry-points.md](../switch-api/entry-points.md#property-ui-callbacks). To let a property hold an empty value under `Standard` validation, add the `none` literal editor to the `Editor` chain (see [property-editors.md § Literal editors](property-editors.md#literal-editors)) instead of relaxing to `Validation="None"` just to permit emptiness. |
+| `Default` | Default value string. Omit only if the value is emitted as CDATA instead. **App guideline (mandatory for apps, recommended for scripts):** always provide a default unless there's genuinely no sensible one; if a default truly isn't possible, give an example value in the `Tooltip` instead. |
+| `Dependency` | Tag of the master property this one depends on. Written flat (not nested) — the dependent element is a sibling of its master, not a child. |
+| `DependencyCondition` | One of: `Not-empty`, `Equals`, `Not-equals`, `Contains`, `Does not contain`, `Matches`, `Does not match`, `Starts with`, `Does not start with`. |
+| `Dependencyvalue` | Value(s) to compare against — `;`-separated for multiple. Note the lowercase `v`. |
+
+**Dependency example** — show `OutputFolder` only when `Mode` equals `"Custom"`:
+
+```xml
+<Mode UserDefined="true" Type="enum:Default;Custom" Editor="inline" Subtype="inline"
+      LocalizedTagName="Mode" Tooltip="" DetailedInfo="" Validation="Standard"
+      Default="Default">Default</Mode>
+<OutputFolder UserDefined="true" Type="string" Editor="choosefolder" Subtype=""
+              Dependency="Mode" DependencyCondition="Equals" Dependencyvalue="Custom"
+              LocalizedTagName="Output folder" Tooltip="" DetailedInfo=""
+              Validation="Standard" Default=""></OutputFolder>
+```
+
+**Runtime pitfall:** when a dependent property is hidden (its master's current value doesn't satisfy
+`DependencyCondition`/`Dependencyvalue`), Switch treats the tag as if it doesn't exist. Calling
+`flowElement.getPropertyStringValue(tag)` on it throws `"Invalid tag: <tag>"` — see
+[flow-element.md](../switch-api/flow-element.md#properties). Only fetch a dependent property once you know
+its condition holds, either by checking the already-read master value yourself, or by calling
+`flowElement.hasProperty(tag)` first (it returns `false` for a hidden dependent). This matters most
+for an enum/drop-down master with several dependents keyed off different values — fetch only the
+ones actually shown for the current selection, not all of them.
+
+A script must never assume the set of fetchable dependents is fixed once at flow configuration
+time: if the master's own value is dynamic (a Switch variable or script expression, resolved per
+job in `jobArrived`), which dependents are shown can differ from job to job in the same flow
+execution. Re-check the condition (or call `hasProperty()`) on every invocation rather than caching
+an earlier "shown" determination. There is no way to read a currently-hidden dependent's value for
+a given job — if a script genuinely needs data from more than one dependency group at once (e.g.
+values entered while the master previously pointed elsewhere), this pattern cannot provide it, and
+a different property structure (not `Dependency`-based hiding) is needed instead.
+
+Attribute order in the file doesn't matter functionally — SwitchScripter's own output happens to be
+alphabetical (QDom sorts attributes on write), but any order parses correctly.
+
+---
+
+## ConnectionFields
+
+Custom outgoing-connection properties follow the same attribute pattern as element properties, with
+one addition: `AvailableFor="Data"` or `AvailableFor="Log"` restricts which connection kind shows the
+property; omit the attribute for both.
+
+```xml
+<ConnectionFields>
+    <TargetFolder AvailableFor="Data" UserDefined="true" Type="string" Editor="choosefolder"
+                  Subtype="" LocalizedTagName="Target folder" Tooltip="" DetailedInfo=""
+                  Validation="Standard" Default=""></TargetFolder>
+</ConnectionFields>
+```
+
+Connection property values are read at runtime via `connection.getPropertyStringValue(tag)`.
+
+**`ConnectionType` gates which built-in connection fields may appear here** — this is the single
+most important thing to get right when hand-editing this section:
+
+| `ConnectionType` | Legal built-in children |
+|---|---|
+| `Move` | none — `<ConnectionFields/>` must be empty of built-ins |
+| `Filter` | `IncludeFolderMask`, `ExcludeFolderMask` (both or neither) |
+| `TrafficLight` | `Success`, `Warning`, `Error`, each optionally with `AvailableFor="Data"` or `AvailableFor="Log"` (omit the attribute if available for both; omit the whole element if available for neither) |
+
+```xml
+<!-- ConnectionType = TrafficLight -->
+<ConnectionFields>
+    <Success AvailableFor="Data" LocalizedTagName="Success out" Type="bool" Editor="inline" Default="Yes">Yes</Success>
+    <Error   AvailableFor="Data" LocalizedTagName="Error out"   Type="bool" Editor="inline" Default="Yes">Yes</Error>
+    <!-- no Warning element: not available for Data or Log -->
+</ConnectionFields>
+```
+
+Custom (author-defined) connection properties may be added regardless of `ConnectionType`.
+
+The declared connections and the script's `sendTo*()` calls must agree with each other — see
+[job-patterns.md § Sending jobs](../switch-api/job-patterns.md#sending-jobs) for the exact rules per
+`ConnectionType`. In particular, omit a `Success`/`Warning`/`Error` element entirely (as shown
+above) if the script never routes to it, rather than leaving an unused connection declared.
+
+**Caution — package-swap connection preservation:** Switch Designer decides whether existing flow
+connections survive a script package replace by comparing the serialised `ConnectionFields` and
+`IncomingConnections` text **byte-for-byte** between old and new declarations, and additionally
+checks whether `ConnectionType`/`OutgoingConnections` changed. Don't make cosmetic whitespace or
+attribute-order changes to those sections without expecting existing flows' outgoing connection
+properties to reset on next package update.
+
+---
+
+## ExtraProperties
+
+Only used for OAuth 2.0 (`Editor` containing `oauth`, see
+[property-editors.md](property-editors.md)). One child element per OAuth property, named
+identically to the property's tag, in `ElementFields` or `ConnectionFields`:
+
+```xml
+<ElementFields>
+    <OAuth1 UserDefined="true" Type="string" Editor="oauth" Subtype="" LocalizedTagName="OAuth1"
+            Tooltip="" DetailedInfo="" Validation="Standard" Default=""></OAuth1>
+</ElementFields>
+<ExtraProperties>
+    <OAuth1 OAuthAuthorizationEndpoint="http://auth-url"
+            OAuthClientID="AppID1"
+            OAuthClientSecret="Application Password 123"
+            OAuthClientSecretEditor="inline"
+            OAuthRedirPorts="666"
+            OAuthRedirPortsEditor="inline"
+            OAuthScope="some-random-scope"
+            OAuthScopeEditor="inline"
+            OAuthTokenEndpoint="http://token-url"/>
+</ExtraProperties>
+```
+
+Attributes: `OAuthAuthorizationEndpoint`, `OAuthClientID`, `OAuthClientSecret`, `OAuthRedirPorts`,
+`OAuthTokenEndpoint`, `OAuthScope`. A companion `<Attr>Editor` attribute is only needed when that
+attribute has more than one valid input mode; otherwise omit it. If the package is
+password-protected, `OAuthClientSecret` must be stored encrypted — leave OAuth secret edits to the
+user rather than writing a plaintext secret into a password-protected package.
+
+If no OAuth property exists on the script, omit `ExtraProperties` entirely or leave it empty
+(`<ExtraProperties/>`).
+
+---
+
+## Type reference
+
+`Type` is a single token, except for enums:
+
+| Token | Meaning |
+|---|---|
+| `string` | Text |
+| `number` | Integer |
+| `password` | Masked text |
+| `bool` | `Yes`/`No` |
+| `date`, `datetime`, `time` | `time` is hours-and-minutes |
+| `path` | Filesystem path |
+| `enum:A;B;C` | Closed choice list, `;`-separated (a trailing `;` is tolerated) |
+| `filefilter`, `folderfilter` | File / folder filter values |
+| `stringlist` | List of strings |
+| `accountlist` | Account list |
+
+This is the *authoring* vocabulary written into the XML `Type` attribute. It does not map one-to-one
+onto the runtime `PropertyType` returned by `getPropertyType()` (see
+[property-editors.md](property-editors.md) and [enums.md](../switch-api/enums.md)) — e.g. XML
+`bool` becomes runtime `boolean`, XML `path` splits into runtime `filepath`/`folderpath`, and several
+XML types (`stringlist`, `accountlist`, `enum:...`, `datetime`, `time`) have no direct
+`PropertyType` counterpart while several runtime values (`filetype`, `folderpattern`, `regex`,
+`oauthtoken`, `literal`) have no direct XML `Type` counterpart. Don't assume the two vocabularies are
+interchangeable.
+
+`rational` (decimal) is not a valid `Type` for Node.js scripts.
+
+`Type` is not independently authored on properties with a modal editor chain — it follows from
+which editor(s) you choose, per [property-editors.md](property-editors.md). When combining
+an inline editor with modal editors (e.g. `Editor="inline;sltextwithvar;scriptexp"`), the inline
+editor's type wins: an inline Number editor plus those modal editors still yields `Type="number"`.
+
+---
+
+## Escaped `ValueDescription` payloads
+
+`SubcategoryInElementPane` (and a couple of internal-only fields) store a nested XML fragment,
+escaped into the text node:
+
+```xml
+<SubcategoryInElementPane Editor="hide">&lt;ValueDescription Type="stringlist">
+ &lt;Value>Communication&lt;/Value>
+&lt;/ValueDescription>
+</SubcategoryInElementPane>
+```
+
+Decodes to:
+
+```xml
+<ValueDescription Type="stringlist">
+  <Value>Communication</Value>
+</ValueDescription>
+```
+
+One `Value` child per subcategory string. Escaping only `<` (not also `&quot;`) is fine — both forms
+parse.
+
+---
+
+## Reserved tag names
+
+A custom property or connection property tag must not collide with any built-in field name. Do not
+use any of:
+
+- Any [built-in `ElementFields` name](#built-in-elementfields) above.
+- Any built-in `ConnectionFields` name: `IncludeFolderMask`, `ExcludeFolderMask`, `Success`,
+  `Warning`, `Error`.
+- `Type`, `Category`, `ElementDescription`, `LogDebugMessages`, `SPSDebugMode`, `SPSDebugPort`,
+  `SPSDebugEntryPoints`, `AbortTimeoutMinutes`, `ScriptPackagePath`, `Xpos`, `Ypos`, `ElementIcon`,
+  `LastModified`, `Path`, `customExecutionMode`, `AdvancedTuningEnabled`, `Hold`, `TrafficType`,
+  `CorneringFactor`, `ElementType`.
+- `ApplicationPath`, `ApplicationLicense` (legal as a tag, but Switch silently drops these two from
+  the flow element's property set, so don't use them). These are app-only properties, set by the
+  user from the Switch Scripter GUI after packing — never modify them directly.
+
+Also required: tag matches `^[A-Za-z][A-Za-z0-9]*$` and does not start with `xml` (case-insensitive).
+
+---
+
+## Annotated example
+
+Representative declaration with Move connections, custom properties, and a dependency chain:
+
+```xml
+<Object>
+    <ElementFields>
+        <Name Editor="hide" Type="string">depositJob</Name>
+        <DisplayName Editor="hide" Type="string"></DisplayName>
+        <Version Editor="hide" Type="number">1</Version>
+        <Keywords Editor="hide" Type="string"></Keywords>
+        <Tooltip Editor="hide" Type="string"></Tooltip>
+        <IncomingConnections RequireAtLeastOne="Yes" Editor="hide">Yes</IncomingConnections>
+        <OutgoingConnections RequireAtLeastOne="Yes" DetailedInfo="" Editor="hide">Unlimited</OutgoingConnections>
+        <ConnectionType Editor="hide">Move</ConnectionType>
+        <FunctionsNodeJSScript Editor="hide">jobArrived</FunctionsNodeJSScript>
+        <ExecutionMode Editor="hide">Concurrent</ExecutionMode>
+        <NumberOfSlots Editor="hide">Default</NumberOfSlots>
+        <ExecutionGroup Editor="hide"></ExecutionGroup>
+        <PerformanceTuning Editor="hide">No</PerformanceTuning>
+        <IdleAfterJob Editor="hide" Type="number">0</IdleAfterJob>
+        <PositionInElementPane Editor="hide">Tools</PositionInElementPane>
+        <DispositionInElementPane Editor="hide" Type="number"></DispositionInElementPane>
+        <Description Editor="hide" Type="string"></Description>
+        <Connections Editor="hide" Type="string"></Connections>
+        <SwitchModule Editor="hide" Type="string">Scripting</SwitchModule>
+        <ObsoleteProperties Editor="hide" Type="string"></ObsoleteProperties>
+        <ObsoleteConnectionProperties Editor="hide" Type="string"></ObsoleteConnectionProperties>
+
+        <!-- Custom property: folder chooser -->
+        <DepositFolder UserDefined="true" Type="string" Editor="choosefolder" Subtype=""
+                        LocalizedTagName="Deposit folder" Tooltip="" DetailedInfo=""
+                        Validation="Standard" Default=""></DepositFolder>
+
+        <!-- Custom property: dropdown enum -->
+        <AttachAs UserDefined="true" Type="enum:Job;Dataset" Editor="inline" Subtype="inline"
+                  LocalizedTagName="Attach as" Tooltip="" DetailedInfo="" Validation="Standard"
+                  Default="Job">Job</AttachAs>
+
+        <!-- Custom property: bool, depends on AttachAs = "Dataset" -->
+        <IncludeMetadata UserDefined="true" Type="bool" Editor="inline" Subtype="inline"
+                          Dependency="AttachAs" DependencyCondition="Equals" Dependencyvalue="Dataset"
+                          LocalizedTagName="Include metadata" Tooltip="" DetailedInfo=""
+                          Validation="Standard" Default="No">No</IncludeMetadata>
+
+        <!-- Custom property: literal "Default" editor combined with a modal editor -->
+        <FallbackFolder UserDefined="true" Type="string" Editor="default;choosefolder" Subtype=""
+                         LocalizedTagName="Fallback folder" Tooltip="" DetailedInfo=""
+                         Validation="Standard" Default="Default">Default</FallbackFolder>
+    </ElementFields>
+    <ConnectionFields/>
+    <ExtraProperties/>
+</Object>
+```

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

@@ -0,0 +1,157 @@
+---
+id: script-structure
+category: switch-project
+order: 10
+summary: "What files a script folder contains, laying out several script folders side by side, `manifest.xml` format, Script vs App, packing an app with SwitchScripter"
+triggers:
+  - "Setting up a new script project or converting a Script to an App"
+---
+
+# 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 [script-declaration.md](script-declaration.md) for the declaration's rules, and [entry-points.md § Entry-point scanner constraints](../switch-api/entry-points.md#entry-point-scanner-constraints) before writing any string/regex literal or division, since certain shapes make Switch's entry-point scanner silently drop functions. Leave `manifest.xml` to the user unless explicitly asked.
+
+<!-- docs-index:contents begin -->
+## Contents
+
+- Script folder files
+- Several script folders side by side
+- manifest.xml format
+- Node.js version per Switch version
+- Script vs App
+- Packing an app
+  - SwitchScripter and Switch version compatibility
+- App Store submission guidelines
+- Execution modes
+<!-- docs-index:contents end -->
+
+## 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 [script-declaration.md](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. Never bundle an Oracle Java Runtime Environment here — licensing terms don't permit redistributing it, in a script or an app. |
+| `<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.
+
+## Several script folders side by side
+
+One script folder produces one flow element. A design that needs several flow elements, such as
+the apps in an app bundle, needs one script folder per element. Keep them in one parent folder, a
+**script collection**:
+
+```
+my-collection/        the folder the user works in; AI agent config and docs live here
+├── FirstElement/     script folder (manifest.xml, FirstElement.xml, main.ts, ...)
+└── SecondElement/    script folder
+```
+
+- Put each script folder directly under the collection, one level down. Don't nest a script folder
+  inside another script folder, and don't add grouping folders in between.
+- Create each one with `SwitchScriptTool --create <ScriptID> <CollectionFolder>`. First check that
+  `<CollectionFolder>/<ScriptID>/` doesn't exist: `--create` deletes an existing target folder and
+  everything in it without asking.
+- Never use `--create` to turn the collection folder itself into a script folder
+  (`--create <CollectionFolderName> <ParentFolder>`). That deletes the whole collection, including
+  `.git/` and AI agent config. If the user wants a script folder at the top level of the folder
+  they work in, or wants an existing top-level script folder moved down into a subfolder, stop and
+  leave that step to the user.
+- Each script folder keeps its own `package.json`, `node_modules/` and `tsconfig.json`. Run npm,
+  transpile and pack per script folder.
+
+## 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` selects the Node.js version the script runs on, and SwitchScriptTool
+and SwitchScripter overwrite it. See [node-versions.md](node-versions.md).
+
+## 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 |
+
+## Packing an app
+
+An app is produced by SwitchScripter, not by SwitchScriptTool, and the two workflows have to be
+joined up explicitly:
+
+- **A script folder can only be typed `Script`.** To ship one as an app, pack it with
+  `SwitchScriptTool --pack` first, then open the resulting package in SwitchScripter and change the
+  type to `App` before creating the `.enfpack`. If "Create pack" is greyed out, the type is still
+  `Script`.
+- **Extra files can't be managed while SwitchScripter is working with a script folder.** Convert to
+  a script package first. The conversion is reversible, so the `.pdesc` holding the extra-files
+  configuration can be round-tripped back into the script folder and kept in version control.
+- **Creating a pack does not save the script.** Save first, or the pack is built from the last
+  saved state.
+- **The pack ID is derived from the script ID and always starts with `com.enfocus.`**, whatever the
+  company name and domain in SwitchScripter preferences. To keep it stable across an update, open
+  the previous `.enfpack` rather than the `.sscript` — SwitchScripter carries the pack ID over from
+  the pack it opened, even if the script ID or domain has since changed.
+
+### SwitchScripter and Switch version compatibility
+
+An app loads in the Switch version it was built with **or newer**, never older. So the SwitchScripter
+used must be at or below the oldest Switch version you intend to support, and portable
+SwitchScripters exist for older releases specifically to build backwards-compatible apps. There is
+no SwitchScripter for Switch 25.11 — use the Switch 2024 Fall SwitchScripter for it.
+Apps as a concept require Switch 13.1 or later.
+
+The SwitchScripter version also fixes the app's Node.js version, see
+[node-versions.md](node-versions.md). An app built with the
+Switch 2024 Fall SwitchScripter has `SwitchVersion` `24.1`, so it runs on Node.js 20 in every Switch
+version that loads it, including 26.x. Switch 26.11 ships SwitchScripter 26.11. An app built with
+it runs on Node.js 24, and it loads only in Switch 26.11 or newer.
+
+An unsigned app loads only in Switch on the machine that created it. That's what allows local
+testing before submission; it loads elsewhere only once Enfocus has signed it.
+
+## App Store submission guidelines
+
+App-specific submission rules (localization, universal/signed macOS binaries, immutable extra
+files) live in [app-guidelines.md § App-only](../switch-appstore/app-guidelines.md#app-only), alongside the
+rest of the pre-publish checklist.
+
+## Execution modes
+
+`Concurrent`/`Serialized`, `ExecutionGroup` and `NumberOfSlots` are set in the XML declaration (see
+[script-declaration.md](script-declaration.md#built-in-elementfields) for the attributes)
+and documented in
+[execution-environment.md § Execution modes](../switch-api/execution-environment.md#execution-modes),
+which also explains why none of them maps to a count of Node.js processes.