procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/procesio/dto/form/FORM-STYLING-NOTES.md

@@ -0,0 +1,142 @@
+# PROCESIO form styling — RESOLVED & implemented (2026-06-25)
+
+All four styling surfaces are now understood (verified against the ui-builder frontend
+source in `docs_info/ui-builder-main`) and buildable via `builder.py`.
+
+> **Building a real form?** This file is the reference for the four *surfaces*. The
+> full development guide — execution model, DOM contract, interaction recipes,
+> custom steppers and motion, process wiring, deployment, and the pitfall catalogue —
+> is [`tools/procesio/FORM-DEV-GUIDE/`](../../FORM-DEV-GUIDE/00-INDEX.md). Those files
+> are written to be attached as chat context.
+
+## 1. Form Theme — ✅ implemented
+`Data.theme`: 18 sections, ~190 CSS variables (`{label,types,properties:[{type,label,
+value,cssVariable}]}`). Pass `theme:{"--c-primary":"#0039e3","--h-input":"44px"}`;
+`_apply_theme` overrides by `cssVariable`. Form-wide, by control type. Defaults =
+`docs_info/form-theme.ts` `getDefaultTheme()` (== `data_shell.json` theme).
+
+## 2. Element event JavaScript — ✅ implemented
+Per-control onClick/onInput/etc → `{action:"RUN_JAVASCRIPT", config:{code}}` (plaintext)
+in the element's event config. `events:[{on:"click",do:"js",code:"..."}]`.
+
+## 3. Per-component styling — ✅ implemented
+Each element has a `{key:"style", category:"styling"}` config whose value is a
+`CSSProperty[]` (`{label,value,cssVariable,type,enabled}`). The runtime
+(`useThemable.themeStyle`) applies ONLY `enabled:true` props, overriding
+`style[cssVariable]=value` (wrapping in `var(value)` when `type==css-variable-select`).
+Build it by passing per-element `style:{cssVariable:value}`:
+```json
+{"type":"input","label":"Name","style":{"--h-input":"50px","--c-input-background":"--c-neutral--50"}}
+```
+- Valid vars = the element type's CSS group (frontend `getCssGroupByElementType`: FIRST
+  theme group whose `types` include the type — so input/number/datetime/textarea/select all
+  use the **Input** group). Unknown var → hard error (lists valid ones). Non-stylable types
+  (heading, paragraph, divider, image…) → error.
+- For `css-variable-select` vars (colors) pass a theme color VARIABLE (e.g. `--c-neutral--50`),
+  NOT a hex — the runtime emits `var(<value>)`. Plain vars (height/padding) take raw values.
+- Builder: `_apply_element_style` + `_style_props_for` (reads groups from `data_shell.json`).
+
+## 4. Form-level CSS + JavaScript ("Switch to code") — ✅ implemented
+Stored encrypted in `Data.code`. **Scheme (verified by decrypting real exports):**
+`code = AES_encrypt( JSON.stringify({"JAVASCRIPT":js,"CSS":css}) )` using CryptoJS
+`AES.encrypt(text, passphrase)` = OpenSSL AES-256-CBC, key+IV via EVP_BytesToKey(MD5,1),
+output `base64("Salted__"+salt+ct)`. Passphrase = a static key.
+- **Key is in Credential Manager**, one per installation, stored per environment as
+  `agents-and-tools:procesio:form-code-key@<environment>` (the bare `form-code-key` is
+  the default environment's; `tools/procesio/form_code_keys.py`) — NEVER in any file
+  (Hard rule 1). Declared in `tool.yaml` secrets.
+- Build via `css:"..."` / `javascript:"..."` (or `code:{css,javascript}`) on the form
+  config. Empty → `code:""` (forms render fine without it). Impl: `code_cipher.py`
+  (`encrypt_code`/`decrypt_code`) + `builder._build_code`.
+- The frontend itself only holds `code` as a plaintext `{JAVASCRIPT,CSS}` object and runs
+  the JS as a RUN_JAVASCRIPT form event at render; the host webapp does the AES step. There
+  is NO plaintext css/js field on the DTO (team confirmed: no unencrypted path).
+
+## 5. Restyling an EXISTING form — use `form-set-code`, never `form-edit`
+`form-edit` is a desired-state editor: it rebuilds the whole DTO from a config, so
+pointing it at a large hand-authored form to change one field means re-declaring every
+element or losing them. Use the surgical pair instead (handlers/form_code.py):
+`form-get-code --id <id>` (decrypt) / `form-set-code --id <id> --css-file … --js-file …`
+(GET → swap `Data.code` → PUT the same DTO back). Only `Data.code` changes; omitting one
+of css/js preserves that side; the overwritten code comes back under `previous`, so a
+mistaken overwrite is recoverable from the tool output alone.
+- `PUT /api/FormTemplate` wants the PascalCase envelope (`Id/Name/IsPrivate/Type/Status/
+  State/Assignees/Data/CustomUrl`) while the GET returns it camelCase — map explicitly.
+
+- **`{"JAVASCRIPT": null, "CSS": null}` is a NORMAL decrypt result, not a corrupt blob.**
+  The designer seeds both slots to null, so that is what every form that never opened
+  "Switch to code" carries — and a form can also carry a JS slot holding only the
+  designer's boilerplate comment. Normalize null → `""` before doing anything with a
+  length or a concatenation (`_decode` does; a `len(None)` crash here was a real bug).
+- **A wrong passphrase and a corrupt blob are indistinguishable at the API layer**: both
+  surface as a `UnicodeDecodeError` after AES runs and emits garbage. Diagnose by
+  round-tripping `encrypt_code`/`decrypt_code` with a throwaway key — if that works, the
+  blob is fine and the KEY is wrong. Note also that the workspace API key (name + value)
+  and the form-code passphrase are DIFFERENT secrets that look alike (short opaque
+  tokens); the API key gets you *at* the form, the passphrase gets you *into* `Data.code`.
+
+## 6. What the CSS and the JS can actually reach at runtime
+- **CSS is injected as a `<style>` PREPENDED INSIDE the form root, and SCOPED to it**
+  (changed in v3.0.0, 2026-10; before, it styled the whole document and page-level
+  selectors worked). Every selector is rewritten to
+  `sel:where([data-form-css-scope=<id>], ...)`, matching the form root and its
+  descendants only. So rules for `body`, `:root`, `html`, the host chrome and the builder
+  match nothing, `:root` custom properties no longer reach the form, and tooltips and
+  date-picker popups no longer get the form CSS. Comments and unparsable CSS are dropped;
+  `@keyframes` / `@font-face` are moved into a layer. Still global: a `<style>` inside
+  paragraph/heading HTML, `@import`, and JS that injects a `<style>` into
+  `window.parent.document`. JS that renders UI OUTSIDE the form container (appended to
+  `document.body`, a modal or overlay, a full-page app) gets no styles, and `:root` /
+  `html` / `body` rules stop applying: before mounting, copy the container's
+  `data-form-css-scope` value onto `<html>` (inside the wait-for-render loop). Full rules
+  and the snippet in `tools/procesio/FORM-DEV-GUIDE/02-CODE-INJECTION.md` §2.
+- **The branding class is also filtered** (`js/form-builder/css.ts` replaces that literal
+  string with a random number so it cannot be hidden).
+- **Form-level JS is replayed as a synthetic RUN_JAVASCRIPT event on mount and on every
+  re-trigger, inside a throwaway sandbox iframe whose window is destroyed and rebuilt each
+  time.** So anything that must OUTLIVE one run (listeners, MutationObservers, timers)
+  cannot live in that scope — it dies with the iframe. The pattern that works: from the
+  sandbox, inject a `<script>` ONCE into `window.parent.document`, carrying the real
+  runtime (`'(' + fn.toString() + ')();'` avoids escaping). Guard both layers with a
+  flag — the installer re-runs, and a second copy means doubled handlers. The platform
+  confirms the reach itself: the JS slot's shipped boilerplate reads
+  `console.log(window.parent.document); -> to access the DOM`.
+- **Controls are re-created, not hidden**: `Element.component.vue` renders under `v-if`,
+  so toggling `visible` removes the node from the DOM. Entrance animations therefore fire
+  on every step change (good), but exit transitions are impossible (the node is gone), and
+  any state you attach to a node must be recomputed from a MutationObserver.
+- **Runtime selectors** are two families: `.form-builder--*` (the renderer's own, e.g.
+  `--form`, `--form-body`, `--element[data-element-id]`, `--stepper--nav--item`,
+  `--stepper--container`, `--stepper--buttons`, `--input`, `--select`, `--checkbox`,
+  `--radiobox`, `--file-upload`, `--columns`, `--column`) and `.pds-c-*` from the design
+  system (`--input-group--wrapper` / `--wrapper--focused` / `--wrapper--is-error`,
+  `--input-group--label`, `--input-group--message--is-error`, `--input-group--square`,
+  `pds-c-radiobox--is-checked`, `pds-c-button--solid-primary`, `pds-c-step--header--circle`
+  `[--active]`, `pds-c-step-connector`). The `pds-c-*` INTERNALS are not in this repo
+  (they ship in `@procesio/procesio-design-system`), so only the ones the renderer's own
+  SCSS references are safe to target — anything deeper must be checked against a live
+  render first.
+
+## Source of truth
+`docs_info/ui-builder-main` is the actual frontend repo. Confirmed: its
+`src/js/model/element/mock.ts` is byte-identical to `FormBuilder mock.ts` (our goldens come
+from it), and its `src/js/model/config/index.ts` enums match `form-config-enums.ts` exactly.
+
+## Dark theme + element alignment (2026-08)
+
+**Dark theme.** A form carries both a light and a dark palette, swapped at runtime by
+`themeMode`/`activeThemeMode` (getPaletteStyleSheet injects the active one). The 16-var
+`DARK_PALETTE` (builder `_DARK_PALETTE`): `--c-primary` #4663f5, `--c-primary-variant`
+#8aa0ff, `--c-error` #ff6b6b, `--c-success` #32d583, `--c-info` #53b1fd, and the neutrals
+inverted `--c-neutral--900` #f8fafd … `--c-neutral--0` #141922. Opt in via config
+`themeMode`/`themeDark`; default forms stay light-only. The exact DTO persistence key for
+the dark palette is best-effort (`themeMode`/`themeDark` in Data) pending live confirmation.
+
+**Element alignment.** Container elements accept three flex vars in their per-control
+`style`, keyed by an element SCOPE suffix: `--fd-<scope>` (flex-direction / "Inner
+direction"), `--jc-<scope>` (justify-content / "Inner main axis"), `--ai-<scope>`
+(align-items / "Inner cross axis"). Scopes: section, list-item, column, step, tab,
+side-panel (element types section, list, columns, stepper, tabs, side-panel). The builder
+accepts them additively today (`_alignment_props`); when the golden `data_shell.json` is
+refreshed from the launched `form-theme.ts` the golden's native definition (proper dropdown
+type + option list) wins.

procesio_cli/tools/procesio/dto/form/GOLDEN-DRIFT-NOTES.md

@@ -0,0 +1,72 @@
+# Form-control goldens: generated from the FormBuilder mock (DO NOT hand-edit)
+
+`elements/<type>.json` (the per-control "goldens" the builder clones) are **generated**
+from the FormBuilder source of truth `docs_info/FormBuilder mock.ts` by
+`sync_from_mock.py`. Do not edit them by hand — your change will be overwritten on the
+next sync. Change the mock (or `enum_map.json`) and re-run instead.
+
+## The sync mechanism — `sync_from_mock.py`
+```
+python tools/procesio/dto/form/sync_from_mock.py            # dry-run: what would change + unverified enums
+python tools/procesio/dto/form/sync_from_mock.py --write    # regenerate all elements/*.json
+python tools/procesio/dto/form/sync_from_mock.py --check    # exit 1 if goldens != mock (CI guard)
+```
+**When a new mock.ts arrives** (new control, changed control, new feature): drop it in
+`docs_info/FormBuilder mock.ts`, run `--write`, eyeball the change list + the
+"UNVERIFIED enum members" section, run the tests. That's the whole loop.
+
+What it guarantees:
+- **complete** — one golden per control the FormBuilder ships (33), incl. ones that
+  could never be harvested (chart, chat, assignee, signature-pad, stepper, step).
+- **exact** — config keys, **render order** (= designer properties-panel order),
+  `type`/`category`/`subCategory`/`exposed`/`events` all come straight from the mock.
+- **deterministic / repeatable** — same mock in → byte-identical files out (ids are
+  `uuid5`; the builder reassigns ids at build time so their values are cosmetic).
+- **sound** — before writing it re-checks every regenerated golden against the previous
+  on-disk one and ABORTS if any *resolved enum value* of a shared config changed
+  (catches a wrong enum mapping). Adding keys a stale golden lacked is allowed.
+
+## Enum resolution — authoritative, no guessing
+The mock references config metadata via enums imported from `../config`. Resolution
+precedence (highest first):
+1. `docs_info/form-config-enums.ts` — the frontend's actual enum definitions (provided
+   verbatim by the team 2026-06-25). Parsed directly → every member is authoritative.
+2. `enum_map.json` — committed fallback / manual override (used only for a member not
+   in the TS file).
+3. rule `MEMBER → lower, '_'→'-'` — last resort, flagged **UNVERIFIED**.
+
+`ElementType` and `ElementCategory` are defined **inside** the mock → parsed from it.
+
+With the TS file present, **0 members are unverified**. Confirmed oddities the rule
+alone would get wrong (now in the TS file): `READONLY_OR_DISABLED_TOGGLE →
+"readonly-or-disabled"` (suffix dropped) and the misspelled `CONTOLS → "controls"`.
+
+**When the frontend changes a config enum:** paste the updated enum into
+`docs_info/form-config-enums.ts` and re-run `--write`. That's the whole enum-upkeep
+story — no manual map editing.
+
+## TEMPLATE_ONLY configs are intentionally excluded  (DECISION — confirmed 2026-06-25)
+Configs typed `TEMPLATE_ONLY` (templateLabel, variation, palette-only duplicates) live
+only in the builder palette, never in an instantiated/saved control — so the generator
+drops them. The golden mirrors **what the toolbar produces**, which is what the builder
+must send. Their absence is correct, not drift. Do NOT re-add them: a real saved control
+has none, and shipping them risks the platform's on-save compiler mishandling the element
+and creates phantom data-model attributes. (To override anyway, the only change is to stop
+skipping `type == "template-only"` in `sync_from_mock.py`.)
+
+## Builder coupling (don't break these)
+`builder._set_config` overrides a key **only if it already exists** in the golden — a
+missing key = silent no-op. That's why golden completeness matters and why we generate
+from the mock. Builder-critical keys verified present: `childrenIdPerColumn`, `rows`,
+`columns`, `tabs`, `tableColumnsSourceType/Value`, canonical `value`
+(`exposed:true` + `events:["EMIT_INPUT"]`).
+
+## Files
+- `sync_from_mock.py` — the generator (this mechanism).
+- `../../docs_info/form-config-enums.ts` — AUTHORITATIVE frontend enum definitions
+  (parsed directly). Update this when the frontend changes a config enum.
+- `enum_map.json` — committed fallback used only if the TS file is absent.
+- `capture_goldens.py` — OLD harvest-from-exports approach, superseded by the above
+  (kept for reference / cross-checking against real saved forms).
+- `elements.bak.premock/` — backup of the pre-sync harvested goldens (safe to delete
+  once you're happy: `rm -r elements.bak.premock`).

procesio_cli/tools/procesio/dto/form/RUN-PROCESS-RESULT-NOTES.md

@@ -0,0 +1,80 @@
+# Form `RUN_PROCESS` synchronous result notes
+
+These notes cover native form output mapping after a synchronous process event. They
+are based on the form builder contract plus a live browser/process/ledger field trace
+on 2026-09-05. The trace is historical and not a public proof packet; publication
+of these notes does not reverify the deployed browser/runtime. Confirm compatibility
+with the target runtime before relying on this response shape.
+
+## Mapping direction
+
+The form builder resolves both input and output mappings with the process variable on
+the left and the form field value path on the right:
+
+- input spec `{to: processVariable, from: formField}`;
+- output spec `{to: formField, from: processVariable}`.
+
+The process side must resolve to the stable process-variable GUID. Re-fetch and compare
+mappings after any process edit that could replace variable IDs.
+
+## Native synchronous writer contract
+
+A successful synchronous process execution is not sufficient for visible output-map
+updates. The form runtime's native writer consumes a process-variable collection from
+the launch response's `content.variable` path. When the process custom response is an
+arbitrary business object without a compatible `variable` member, the process can:
+
+- finish successfully;
+- write its database/data-store side effect;
+- return a useful object to an API caller;
+- yet leave the form's mapped result fields unchanged.
+
+For a process shared by form, CLI, and subprocess callers, use a compatibility envelope
+rather than replacing the established response:
+
+```json
+{
+  "decision": "<existing top-level field>",
+  "summary": "<existing top-level field>",
+  "next_action": "<existing top-level field>",
+  "duplicate": false,
+  "response": {"<optional complete original response>": "..."},
+  "variable": ["<exact live process-variable instance objects>"]
+}
+```
+
+The example is structural, not a DTO to copy literally. Through an approved protected
+inspection, establish the exact entry shape, IDs, value encoding, list flags and types
+expected by the deployed runtime. Do not return the entire instance variable array:
+only expose outputs the form caller is authorized to see, never credentials or internal
+state. Keep existing permitted business fields at their established top-level paths.
+
+Point the process custom response at the compatibility envelope and keep the ordinary
+process outputs present. Bind any Node/Javascript Error output and set a nonzero timeout.
+
+## Proof standard
+
+A native output-mapping claim passes only when one real form interaction:
+
+1. opens the published form in a clean browser context;
+2. submits or clicks exactly once with a stable business key;
+3. observes the real launch response;
+4. updates the mapped fields automatically through the platform event path;
+5. shows the expected decision and non-empty next action;
+6. reconciles the exact process instance and storage side effect;
+7. has no unexplained console, page, network, or response errors.
+
+Do not call the SPA writer manually, patch result fields in the DOM, replay the request,
+or feed an older instance into the writer as proof. Those techniques may diagnose the
+expected shape, but they do not verify the native form path.
+
+## Secret and compatibility rules
+
+- Never store an access token as a form default or in plaintext form code.
+- Exclude secrets before screenshot, log or response capture; masking afterward cannot
+  undo an earlier disclosure.
+- Snapshot process variable IDs and the old custom-response shape before editing.
+- Re-fetch dependent forms and subprocess mappings after the edit.
+- Preserve direct CLI/subprocess response semantics; additive envelopes are safer than
+  replacing an established response object.
+- Count the form-triggered process and every awaited/nested child in execution budgets.

procesio_cli/tools/procesio/dto/form/addelement.py

@@ -0,0 +1,277 @@
+"""Add one or more controls to a LIVE form, without disturbing anything already on it.
+
+The gap this fills: `form-create` speaks an authoring config and `form-edit` rebuilds a whole form
+from one, so neither can add a control to a form that was hand-built in the designer — the two
+shapes are different languages (an authoring config has no element ids at all, see
+PROCESIO-API-NOTES.md "form-create takes an AUTHORING CONFIG"). Every other form action here is
+surgical; adding a control was the missing verb, and without it a new admin button meant
+hand-writing a stored element DTO.
+
+What makes a splice safe rather than a rebuild: PROCESIO backs each control with a data-model
+sub-model whose id IS the element id, and whose attribute ids ARE that element's own config ids
+(see `_build_data_model` in builder.py). New controls therefore contribute new sub-models and touch
+nothing else — which is the whole point, because a RUN_PROCESS/MAP trigger references a field by the
+path `root.fields.elementId.valueAttrId`. Regenerating the live model would silently break every
+mapping already on the form, so this never rebuilds it; it appends to it.
+
+Pure: takes the form as GET returns it, returns a NEW `Data` dict. The caller validates and PUTs.
+"""
+from __future__ import annotations
+
+import copy
+import json
+import re
+import uuid
+
+from tools.procesio.dto.form import builder
+from tools.procesio.errors import UsageError
+
+
+def _new_id(_ctx=None) -> str:
+    return str(uuid.uuid4())
+
+
+def _name_of(element: dict) -> str | None:
+    for c in element.get("configs") or []:
+        if c.get("key") == "name":
+            return c.get("value")
+    return None
+
+
+def _sub_model(element: dict, fields_ns: str, ctx: dict) -> dict:
+    """The `fields` sub-model for one control — element id, config ids, same as a full build.
+
+    Mirrors `builder._build_data_model`'s per-element branch. It is duplicated rather than shared
+    because that function rebuilds the WHOLE model from the shell, which is exactly what a splice
+    must not do to a designer-built form.
+    """
+    eid = element["id"]
+    name = _name_of(element) or eid
+    sub = {"id": eid, "dataTypeId": eid, "name": name, "displayName": name,
+           "isDataModel": True, "isList": False, "isProcesio": False,
+           "isPublic": False, "parentDataTypeId": fields_ns, "jsonProperty": None,
+           "attributes": []}
+    for c in element.get("configs") or []:
+        shape = builder._dm_shape(element, c)     # the same rule form-create applies
+        if shape is None:
+            continue
+        sub["attributes"].append(
+            builder._dm_attr(builder._attr_name(c["key"]), c.get("id") or _new_id(ctx),
+                             shape[0], eid, shape[1]))
+    return sub
+
+
+# container type -> the config holding the ordered NAMES of the children it renders.
+_LIST_CONFIG = {"tabs": "tabs", "table": "rows", "stepper": "steps"}
+
+
+def unreachable_in_row(elements: list, parent_id: str | None) -> str | None:
+    """Warn when a control is being placed where no process map can read it.
+
+    A control inside a table row exists once per row, so a map reads it through the ROW - a
+    five-segment path ending at the child element, via the row's `$.fields` model attribute. A row
+    that was itself spliced in has no `$.fields`: this function builds a sub-model from an element's
+    own configs, and there is no way to add one afterwards that the runtime will honour. The control
+    then displays fine, accepts typing, and sends nothing, which looks like a broken save rather
+    than a control in the wrong place.
+
+    Returns the warning text, or None when the placement is fine.
+    """
+    if not parent_id:
+        return None
+    by_id = {e.get("id"): e for e in elements}
+    node = by_id.get(parent_id)
+    seen = set()
+    while node is not None and node.get("id") not in seen:
+        seen.add(node.get("id"))
+        if node.get("type") == "dynamic-table-row":
+            name = _name_of(node) or node.get("id")
+            return (f"placed inside the table row {name!r}: a control there exists once per row, so "
+                    f"a RUN_PROCESS map reading its own field path gets nothing. Address it through "
+                    f"the row (formId.fieldsNs.rowId.$fieldsAttrId.childId), or - if that row has no "
+                    f"'$.fields' attribute, which is the case for any row that was itself spliced in "
+                    f"- put the control outside the row and copy the value out from the row's "
+                    f"'$.item' when the panel opens.")
+        node = by_id.get(node.get("parentId"))
+    return None
+
+
+def _resolve_parent(elements: list, parent: str | None) -> str | None:
+    if not parent:
+        return None
+    for el in elements:
+        if el.get("id") == parent or _name_of(el) == parent:
+            return el["id"]
+    known = ", ".join(sorted(n for n in (_name_of(e) for e in elements) if n))
+    raise UsageError(f"parent element not found: {parent!r}. Known element names: {known}")
+
+
+def add_elements(form: dict, specs: list, *, parent: str | None = None) -> dict:
+    """Return a NEW `Data` with `specs` (authoring-config elements) appended.
+
+    `parent` places them inside an existing container, by element name or id; omitted, they land at
+    the top level. A duplicate control NAME is refused: the designer resolves a field path back to a
+    name, so two controls sharing one make every reference to it ambiguous.
+    """
+    if not specs:
+        raise UsageError("nothing to add: pass at least one element spec")
+
+    data = copy.deepcopy(form.get("data") or form.get("Data") or {})
+    elements = data.get("elements") or []
+    existing_names = {n for n in (_name_of(e) for e in elements) if n}
+
+    parent_id = _resolve_parent(elements, parent)
+
+    # The field-name resolver walks from the form handle variable into Data.dataModel, so the model
+    # root, the field-path root and variables[0].id must be the SAME id (builder.build guards this
+    # on a full build). On a splice we adopt the LIVE id rather than deriving a new one.
+    handle = (data.get("variables") or [{}])[0]
+    root_id = data.get("dataModel", {}).get("id") or handle.get("id")
+    if not root_id:
+        raise UsageError("form has no dataModel root id; refusing to guess one")
+
+    ctx = {"form_id": form.get("id") or form.get("Id"), "dm_root_id": root_id,
+           "field_paths": {}, "value_attr_ids": {}, "new_id": _new_id,
+           "parent_id": parent_id}
+
+    added: list = []
+    for spec in specs:
+        name = spec.get("name") or builder._field_slug(spec.get("label") or spec.get("type") or "")
+        if name in existing_names:
+            raise UsageError(
+                f"the form already has a control named {name!r}; two controls with one name make "
+                f"every field reference to it ambiguous")
+        existing_names.add(name)
+        builder._build_element(spec, dict(ctx), added)
+
+    data["elements"] = elements + added
+
+    # A container does not draw a child just because the child points at it: `tabs` lists its tab
+    # NAMES and `table` lists its row names, and a spliced child that is missing from that list
+    # exists, saves, lints clean, and never appears on screen. Registering it here is the whole
+    # difference between a control that is there and one that only looks like it is.
+    if parent_id:
+        container = next((e for e in elements if e.get("id") == parent_id), None)
+        if container is not None:
+            key = _LIST_CONFIG.get(container.get("type"))
+            if key:
+                for c in container.get("configs") or []:
+                    if c.get("key") == key:
+                        listed = list(c.get("value") or [])
+                        for el in added:
+                            nm = _name_of(el)
+                            if el.get("parentId") == parent_id and nm and nm not in listed:
+                                listed.append(nm)
+                        c["value"] = listed
+
+    model = data.setdefault("dataModel", {"id": root_id, "name": "form", "attributes": []})
+    attrs = model.setdefault("attributes", [])
+    fields = next((a for a in attrs if a.get("name") == "fields"), None)
+    if fields is None:
+        fields = {"id": builder._FIELDS_NS, "dataTypeId": builder._FIELDS_NS, "name": "fields",
+                  "displayName": "fields", "isDataModel": True, "isList": False,
+                  "isProcesio": False, "isPublic": True, "parentDataTypeId": root_id,
+                  "jsonProperty": None, "attributes": []}
+        attrs.append(fields)
+    fields.setdefault("attributes", []).extend(
+        _sub_model(el, fields["id"], ctx) for el in added)
+
+    return data
+
+
+def _descendants(elements: list, root_id: str) -> list:
+    """Every element under `root_id`, however deep."""
+    out, frontier = [], {root_id}
+    while frontier:
+        kids = [e for e in elements if e.get("parentId") in frontier and e not in out]
+        if not kids:
+            break
+        out += kids
+        frontier = {k["id"] for k in kids}
+    return out
+
+
+def _references_to(data: dict, doomed_ids: set) -> list:
+    """Where the rest of the form still points at one of `doomed_ids`.
+
+    A field VALUE PATH carries the element id, so a RUN_PROCESS input/output map, a visibility
+    condition or another control's event all show up as the id appearing outside the element
+    itself. Searching by id is exact; a reference made by NAME cannot be found this way, which
+    is why the report says so rather than implying the list is exhaustive.
+    """
+    survivors = {"elements": [e for e in (data.get("elements") or [])
+                             if e.get("id") not in doomed_ids],
+                 "events": data.get("events"), "variables": data.get("variables")}
+    blob = json.dumps(survivors, ensure_ascii=False)
+    # Matched as a WHOLE token: a field path joins ids with dots, so an id must not be found
+    # merely because it is a substring of a longer one.
+    return sorted(i for i in doomed_ids
+                  if re.search(r"(?<![0-9A-Za-z-])%s(?![0-9A-Za-z-])" % re.escape(i), blob))
+
+
+def delete_element(form: dict, element: str, *, force: bool = False) -> tuple[dict, dict]:
+    """Return (a NEW `Data` without `element`, report). The mirror of `add_elements`.
+
+    Removes the control from `Data.elements` AND its entry from the form's data model, leaving
+    every other element's id and field path untouched - the property that makes a splice safe
+    and is equally required here. A control that something still references is REFUSED unless
+    `force`, because a dangling field path is saved without any error and the control that
+    pointed at it then silently launches nothing.
+    """
+    data = copy.deepcopy(form.get("data") or form.get("Data") or {})
+    elements = data.get("elements") or []
+    target = next((e for e in elements
+                   if e.get("id") == element or _name_of(e) == element), None)
+    if target is None:
+        known = ", ".join(sorted(n for n in (_name_of(e) for e in elements) if n)[:20])
+        raise UsageError(f"no element with id or name {element!r} on this form; known: {known}")
+
+    kids = _descendants(elements, target["id"])
+    if kids and not force:
+        raise UsageError(
+            f"{_name_of(target) or target['id']!r} contains {len(kids)} control(s) "
+            f"({', '.join(str(_name_of(k) or k['id']) for k in kids[:6])}); delete those first, "
+            f"or pass --force to remove the whole subtree")
+
+    doomed = [target] + kids
+    doomed_ids = {e["id"] for e in doomed}
+    refs = _references_to(data, doomed_ids)
+    if refs and not force:
+        raise UsageError(
+            f"{_name_of(target) or target['id']!r} is still referenced by the form "
+            f"({len(refs)} id reference(s) outside the control itself: an event, a process "
+            f"input/output map or a visibility condition). Re-point or remove those first, or "
+            f"pass --force to delete anyway and break them")
+
+    data["elements"] = [e for e in elements if e["id"] not in doomed_ids]
+
+    # Un-register from a container's own list, the reverse of the splice.
+    for container in data["elements"]:
+        key = _LIST_CONFIG.get(container.get("type"))
+        if not key:
+            continue
+        for c in container.get("configs") or []:
+            if c.get("key") == key and isinstance(c.get("value"), list):
+                gone = {_name_of(e) for e in doomed}
+                c["value"] = [n for n in c["value"] if n not in gone]
+
+    # And from the data model, so the form stops advertising a field it no longer draws.
+    removed_attrs = 0
+    fields = next((a for a in (data.get("dataModel", {}).get("attributes") or [])
+                   if a.get("name") == "fields"), None)
+    if fields:
+        before = len(fields.get("attributes") or [])
+        fields["attributes"] = [a for a in (fields.get("attributes") or [])
+                                if a.get("id") not in doomed_ids]
+        removed_attrs = before - len(fields["attributes"])
+
+    report = {
+        "removed": [{"id": e["id"], "type": e.get("type"), "name": _name_of(e)} for e in doomed],
+        "descendants": len(kids),
+        "model_attributes_removed": removed_attrs,
+        "broken_references": refs if force else [],
+        "element_count": len(data["elements"]),
+        "note": ("references are found by element id; one made by NAME cannot be detected that "
+                 "way, so check a condition that names the control"),
+    }
+    return data, report