--- name: simulator-smart-forms description: > Simulator.Company Smart Form (CDU / Script / Application) specialist. Use when the user wants to create, edit, inspect, or deploy a Smart Form; work with its pages, locale, viewModel, styles, definitions, or widgets; understand the CDU page protocol; pull or push form files; manage releases; or ask questions about the app_content / applications / releases / file_history APIs. Activate on: "smart form", "CDU", "script application", "pullSmartForm", "pushSmartForm", "page config", "viewModel", "locale", "deploy smart form", "edit page layout", "add component to CDU", "rollback release". --- # 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 ```json { "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 ```jsonc { "type": "one_column" | "two_column", "header": { "class": "default" | "steps", "extra": { "steps": ["Step 1", "Step 2"], "active": 1 } }, "components": { "header": [""], "left": [""], "center": [""], "right": [""], "footer": [""], "sidebar": [""] }, "styleClass": "custom-grid" } ``` ### Form ```jsonc { "id": "info", "title": "Details", "styleClass": "card", "visibility": "visible", // "visible" | "disabled" | "hidden" "sections": [ /* Section[] */ ] } ``` ### Section ```jsonc { "id": "s1", "type": "body", // "body" | "block" | "modal" | "float" "visibility": "visible", "header": [ /* Item[] — Label | Button only */ ], "content": [ /* Item[] — the main items */ ] // modal-only: "modalHeader": [ /* Item[] */ ], // "modalSize": "small"|"medium"|"large"|"xlarge", // "modalCloseConfirmText": "…" } ``` `block` renders as a grouped card; `modal`/`float` are overlays. > ⚠️ **A section has no `footer`** — only `header` and `content` (plus `modalHeader` for modals). > Put bottom-of-form actions as the last items in `content`, or in a separate form bound to the > grid's `footer` region. (The grid's `components.footer` above holds **form ids**, not items.) --- ## Component Catalogue Every item has `class` + base fields (`id`, `value`, `visibility`, `required`, `error`, `errorMsg`, `styleClass`, `row`, `w`). Below are the most common components: > **Layout/rendering gotchas** (verified live — full list in > `docs/user-flows/cdu-page-protocol.md` §12): `row` renders as a CSS **table** so its items > **do not wrap** (use `display:inline-block` items directly in `content` for a wrapping grid); > `styleClass` on a `row` is dropped from the DOM (style leaf items, not the `row`); a `radio`/`select` > option dot is a JSS-hashed `