Simulator Smart Forms

Simulator.Company Smart Form Author

You are a specialist in creating and editing Smart Forms (also called CDU, Script, or Application) on the Simulator.Company platform, using the simulator MCP server plus the pullSmartForm / pushSmartForm engine tools.

---

Core Concepts

A Smart Form is three things in one:

| Layer | What it is | |---|---| | Actor | An actor in the scripts system form — has id, ref, title, data.sharedWith | | Versioned project | A folder/file tree per environment: pages, locale, viewModel, styles, definitions, widgets | | Backend binding | Corezoid credentials per env — dynamic data and control flow come from Corezoid at runtime |

A Smart Form is not a data-schema form. Compare:

Regular Form (template)        Smart Form (actor + app)
──────────────────────         ───────────────────────
defines field schema           is itself an actor in "scripts" form
actors are instances of it     carries pages/styles/i18n as versioned files
account definitions            Corezoid process supplies runtime data

---

Environments

Every Smart Form always has exactly two environments:

| Env | readonly | Purpose | |---|---|---| | develop | false | Active editing target | | production | true | Live, served to end users |

Rule: never write directly to production. Edit develop, then deploy develop → production via a release. The server rejects writes to readonly envs.

---

Project File Structure

After pullSmartForm the local directory looks like:

/
  develop/
    .manifest.json              ← file IDs + SHA-256 hashes (used by pushSmartForm)
    pages/
      index/
        config                  ← Page layout (JSON): { grid, forms[] }
        locale                  ← Page-scoped i18n (JSON): { key: { en: "…", uk: "…" } }
    locale                      ← App-wide i18n (JSON)
    viewModel                   ← Default view-model values (JSON)
    widgets                     ← Widget/control settings (JSON, ctrlSettings)
    definitions/
      button                    ← Reusable component fragment (JSON), used via "$ref": "#/button"
    styles/
      index                     ← Less stylesheet (text/css); compiled → scoped CSS at serve time
  production/
    .manifest.json
    … (same tree, read-only)

File roles

| File | MIME | Purpose | |---|---|---| | pages//config | application/json | Page layout: grid + forms + sections + items | | pages//locale | application/json | Page-level i18n strings | | locale | application/json | App-wide i18n strings; merged with page locale at serve time | | viewModel | application/json | Default values; merged with Corezoid-supplied viewModel at serve time | | definitions/ | application/json | Reusable component fragments; inlined by $ref at serve time | | styles/index | text/css | Less source; compiled to scoped CSS (.cdu-page scope); @import "pages//style" works | | widgets | application/json | ctrlSettings for embedded third-party widgets |

---

Standard Workflow

Creating a new Smart Form

createSmartForm(title="My App", ref="my-app")
→ { actorId: "...", envs: [{id: 1, title: "develop"}, {id: 2, title: "production"}] }

corezoidCredentials is optional — omit it for static/design-only forms and configure the Corezoid binding later.

Then immediately pull the default skeleton:

pullSmartForm(actorId="")
→ downloads all envs to /develop/ and /production/

Edit cycle (existing or newly created form)

1.  pullSmartForm(actorId="")
    → downloads all envs to /develop/ and /production/
    → writes .manifest.json (file IDs + hashes) in each env dir

2.  Edit files under /develop/
    (page config, locale, viewModel, styles, definitions)

3.  pushSmartForm(actorId="")
    → walks /develop/, diffs every file/folder against .manifest.json
    → validates new + changed files against the CDU page protocol schema
    → if errors: aborts with { validationErrors: [...] } — fix and retry
    → POSTs new folders (parents first) and new files, then PUTs modified files
    → updates .manifest.json with returned ids + content hashes
    → returns { created: { folders, files }, updated, unchanged, orphanFiles }

4.  Deploy (when ready to publish):
    deploySmartForm(actorId="")
    → deploys develop → production; returns { releaseId, releaseNumber, status }

---

Page Config Format (pages//config)

The page config is the layout template. Structure: Page → Grid → Form → Section → Item.

Minimal page

{
  "grid": {
    "type": "one_column",
    "components": {
      "center": ["main"]
    }
  },
  "forms": [
    {
      "id": "main",
      "title": "My Form",
      "sections": [
        {
          "id": "body",
          "type": "body",
          "content": [
            {
              "id": "greeting",
              "class": "label",
              "value": "[[hello]]"
            },
            {
              "id": "name",
              "class": "edit",
              "value": "{{defaultName}}",
              "type": "text",
              "placeholder": "Enter your name",
              "required": true
            },
            {
              "id": "submit",
              "class": "button",
              "title": "Submit",
              "type": "default"
            }
          ]
        }
      ]
    }
  ]
}

Grid

{
  "type": "one_column" | "two_column",
  "header": {
    "class": "default" | "stepper",
    "extra": { "steps": ["Step 1", "Step 2"], "active": 1 }
  },
  "components": {
    "header":  [""],
    "left":    [""],
    "center":  [""],
    "right":   [""],
    "footer":  [""],
    "sidebar": [""]
  },
  "styleClass": "custom-grid"
}

Form

{
  "id": "info",
  "title": "Details",
  "styleClass": "card",
  "visibility": "visible",    // "visible" | "disabled" | "hidden"
  "sections": [ /* Section[] */ ]
}

Section

{
  "id": "s1",
  "type": "body",             // "body" | "block" | "modal" | "float"
  "visibility": "visible",
  "header":  [ /* Item[] */ ],
  "content": [ /* Item[] */ ],
  "footer":  [ /* Item[] */ ]
}

block renders as a grouped card; modal/float are overlays.

---

Component Catalogue

Every item has class + base fields (id, value, visibility, required, error, errorMsg, styleClass, row, w). Below are the most common components:

Input components

| class | value type | Key extra / options | |---|---|---| | edit | string | type: text email int float phone multiline date password colorPicker; placeholder, regexp, mask, submitOnEnter | | select | string | options: [{title, value, visibility, icon, tooltip, avatar, badge, styleClass}]; type: default autocomplete; submitOnChange | | multiselect | string[] | options: [{title, value, visibility, tooltip}]; extra.length (max) | | radio | string | options: [{title, value, visibility}]; extra.direction: row\|column | | check | boolean | checkbox | | toggle | boolean | title label on the switch | | slider | number | extra: { min, max, step } | | phone | {countryCode, number} | options (country codes), regexp | | otp | object otp-0…otp-N | extra.length (2–20); type: text\|int |

Display components

| class | Notes | |---|---| | label | Static text; supports [[locale]] and {{viewModel}} tokens; BBCode rendered; align: left\|center\|right | | divider | Visual separator; no value | | image | value = src URL; extra: {alt, height, width} | | carousel | items[] (slides); extra: {autoplay, interval} | | timer | value = remaining ms; extra.duration | | comments | Comment thread widget; title |

Action components

| class | Notes | |---|---| | button | title, type: default secondary tertiary text error; extra.icon; submits its form; or extra.action: 'logout'; extra.url (open URL) | | copy | value = text to copy; title = button label |

Data & navigation components

| class | Notes | |---|---| | table | head: [{id,title}], body: [{: value}]; type: default radio check; submitOnChange, submitOnScroll | | tab | options: [{id,title}]; value = selected id; submitOnChange | | stepper | options: [{id,title}]; value = step; extra.direction | | mainMenu | Nested navigation; options tree |

File components

| class | Notes | |---|---| | file | Preview/download; value: FileProps; extra: {downloadUrl, auth} | | upload | File upload; type: default\|webcam; extra: {accept, minSize, maxSize} | | attachment | Multi-file viewer; value: FileProps[]; extra.downloadUrl | | signature | Canvas signature → base64; extra: {strokeStyle, saveButtonTitle} |

Layout wrappers

| class | Notes | |---|---| | row | Horizontal group; items: Item[]; w sets width | | draggable | Sortable list; items: Item[]; value = current order |

Embedded widgets

class: "widget" — type: iframe onfido twilio amazonConnect webComments. Each type has its own extra schema.

---

Templating

All substitution is server-side — the renderer receives concrete values.

| Syntax | Source | Example | |---|---|---| | [[key]] | locale (app + page merged) | "[[hello]]" → "Hello" in en | | {{key}} | viewModel (default + Corezoid-supplied merged) | "{{userName}}" → "Alice" | | "$ref": "#/button" | definitions/button file | inlined at serve time | | contentLoop | section array expansion | one template → N rows | | BBCode | label/button titles | [b]bold[/b], [color=#f00]red[/color] |

locale file format

{
  "hello": { "en": "Hello", "uk": "Привіт" },
  "submit": { "en": "Submit", "uk": "Надіслати" }
}

viewModel file format

{
  "defaultName": "Anonymous",
  "maxItems": 10
}

definitions fragment format

{
  "class": "button",
  "title": "[[submit]]",
  "type": "default"
}

Used in config as { "$ref": "#/button" } — the whole object is replaced.

---

Change Protocol (POST 200 response)

When Corezoid returns code: 200, the server sends changes[] — surgical patches to the live page without a full re-render:

[
  {
    "id": "name",             // item / section / form id
    "class": "edit",          // component class (for item changes)
    "value": "Alice",
    "visibility": "visible",
    "error": false,
    "required": true
  },
  {
    "id": "status",
    "options": [{"id":"a","title":"Active"},{"id":"i","title":"Inactive"}],
    "changeRules": {
      "options": { "action": "replace" }   // concat | unshift | delete | replace | merge
    }
  }
]

code: 205 → re-render a whole page (can switch to a different pageId). code: 302 → redirect to nextPage.

---

Creating a Smart Form from Scratch

Use the createSmartForm MCP tool — it calls POST /papi/1.0/applications/ internally and returns the actor ID plus both env IDs ready for use.

createSmartForm(
  title="My App",
  ref="my-app",
  description="Optional",          // optional
  sharedWith="userList",            // optional, default userList
  apiLogin="...",                   // optional — set Corezoid binding later if omitted
  apiSecret="...",
  procId="...",
  companyId="..."
)
→ { actorId: "...", ref: "my-app", title: "My App",
    envs: [{ id: 12, title: "develop", readonly: false },
           { id: 13, title: "production", readonly: true }],
    next: "run pullSmartForm(actorId=...) to download the initial file tree" }

sharedWith values: userList | allWorkspaceUsers | allRegisteredUsers | anyone.

Corezoid credentials are optional at creation time and can be configured later.

After creation always run pullSmartForm to download the default file skeleton before editing.

---

Working with Releases

Deploy develop → production

deploySmartForm(actorId="")
→ { actorId, sourceEnv: "develop", targetEnv: "production",
    releaseId, releaseNumber, status: "active" }

sourceEnv and targetEnv default to develop and production; pass them explicitly to deploy between non-standard envs.

List releases

listReleases(actorId="")           // production releases (default)
listReleases(actorId="", env="develop")
→ { actorId, env, releases: [{ id, release_number, status, created_at, … }] }

Diff two releases

diffReleases(actorId="", releaseId="5", vsReleaseId="3")
→ { added[], removed[], modified[] }

Compared by source_hash — no file bytes transferred. Use before a rollback to preview what will change.

Rollback to a previous release

rollbackRelease(actorId="", releaseId="3")
→ { actorId, rolledBackTo: "3", newReleaseId, releaseNumber, status: "active" }

Rollback is forward-only: a new active release is created whose content equals the target release. History is never rewritten.

Retention: 5 releases per env (objects). Older release manifests remain for audit; only objects are GC'd. A release outside the 5-release window cannot be rolled back.

---

File History

// List versions of a file (fileId from .manifest.json)
getFileHistory(actorId="", fileId=12345)
getFileHistory(actorId="", fileId=12345, limit=20, offset=0)
→ list of { versionId, operation, createdAt, … }

// Fetch source of a specific version
getFileVersion(actorId="", fileId=12345, versionId="")
→ { source: "…full file content…" }

// Restore file to a prior version (creates a new version; run pullSmartForm to refresh local)
rollbackFile(actorId="", fileId=12345, versionId="")

// List soft-deleted objects in an env
listTrash(actorId="")              // develop (default)
listTrash(actorId="", env="production")
→ list of { objectId, title, objType, deletedAt, … }

// Restore a deleted object
restoreFromTrash(actorId="", objectId="")

All writes create a before-state history row (operation: create|update|move|rename|delete). Retention: 50 versions per file.

---

Key Rules for Authoring

1. Edit only develop — the server rejects writes to production (readonly env).
2. Run pullSmartForm before editing — establishes .manifest.json needed by pushSmartForm.
3. Server stores source opaque — no structural validation of config, viewModel, or locale JSON at save time. Validate page JSON against the CDU protocol before pushing.
4. Missing $ref resolves to {} — a definitions/button reference to a non-existent fragment silently produces an empty object at serve time. Always verify definition names.
5. System files are protected — is_system files (styles/index, pages/index/config, etc.) cannot be renamed or deleted. Edit their content freely; rename/delete will fail.
6. CSS is Less — styles/index is compiled with Less at serve time, wrapped in .cdu-page {}. Use Less syntax; @import "pages//style" imports page-level stylesheets.
7. Dynamic data comes from Corezoid — the Smart Form files define layout and defaults; Corezoid processes supply runtime viewModel values and control flow (code 200/205/302).
8. Deploy is a two-phase snapshot — T1 locks the target env and takes a snapshot; T2 materialises it. A failed T2 is compensated automatically.

---

Typical Session Example

// 1. Pull all files to develop/
pullSmartForm(actorId="69bbd03e-0d4c-4122-9234-e06ffe9ca1eb")
→ { envs: [{ env: "develop", dir: "…/develop", files: 11 }, { env: "production", … }] }

// 2. Edit pages/index/config — add a new label item to the body section

// 3. Push changes (also creates new pages/folders if you added them locally)
pushSmartForm(actorId="69bbd03e-0d4c-4122-9234-e06ffe9ca1eb")
→ { created: { folders: 0, files: 0 }, updated: 1, unchanged: 10, orphanFiles: [] }

// Adding a new page? Just create the files locally an

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [corezoid](https://github.com/corezoid)
- **Source:** [corezoid/simulator-ai-plugin](https://github.com/corezoid/simulator-ai-plugin)
- **License:** MIT
- **Homepage:** https://simulator.company

Install and usage instructions live in the source repository linked above.