@qontinui/shared-types 0.14.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qontinui/shared-types",
-  "version": "0.14.0",
+  "version": "1.0.0",
   "description": "Shared TypeScript types for the Qontinui ecosystem",
   "type": "module",
   "main": "./dist/index.js",

package/src/generated/UIBridgeElement.d.ts

@@ -41,8 +41,55 @@ export interface UIBridgeElement {
   bbox?: ElementBbox | null;
   /**
    * Custom (application-defined) actions.
-   */
-  customActions?: string[] | null;
+   *
+   * **Objects, not names.** These used to be a bare `Vec<String>` of action
+   * names, which left an element-level custom action with nowhere to carry a
+   * safety class — so the walker had no way to tell a `refresh` from a
+   * `sendKeys` that writes raw bytes into a live agent PTY. Widening this to
+   * [`ElementActionInfo`] is what makes `effect` REACHABLE from an element;
+   * see that type's docs.
+   *
+   * Absent (`None`) means the element declares none. That is deliberately
+   * distinct from an empty list, which would mean "declared, and empty".
+   * ---
+   *
+   * **TRANSITIONAL: this field also accepts the legacy bare-NAME form on the
+   * way in.** `["sendKeys"]` deserializes as
+   * `[ElementActionInfo { id: "sendKeys", .. }]`, with every other field —
+   * `effect` included — left `None`, i.e. UNCLASSIFIED. See
+   * [`deserialize_custom_actions`].
+   *
+   * **Why a shim exists at all**, when this workspace's rule is
+   * delete-over-deprecate. The shape change spans three repos that cannot
+   * land atomically — this crate owns the type, `ui-bridge` emits, and
+   * `qontinui-runner` parses live SDK snapshots strictly
+   * (`spec-check/src/fetch.rs`, `spec_api/spec_check.rs`) while pinning a
+   * PUBLISHED SDK. Both two-party orderings leave a window in which the
+   * fleet is broken: land this crate first and the runner rejects the names
+   * the published SDK still emits; land the SDK first and it emits objects
+   * at a runner whose type is still `Vec<String>`. Only a tolerant READER
+   * removes the window, and there is one reader against nine emitters.
+   *
+   * This is NOT here to spare a caller a breaking change — that is never a
+   * reason in this workspace.
+   *
+   * **DELETE ME, and the trigger is observable rather than intentional:**
+   * once no emitter produces names — `ui-bridge`'s eight element
+   * projections plus `qontinui-runner`'s
+   * `src/services/background-observer-service.ts` — and the runner's SDK pin
+   * has moved past that release, remove [`deserialize_custom_actions`] and
+   * this attribute, and flip
+   * `ui_bridge_element_tolerates_legacy_name_custom_actions` into a test
+   * that asserts a bare string is REJECTED. Plan
+   * `2026-09-04-effect-calculus-joins-the-component-action-registry`,
+   * Design decision 4, step 5.
+   *
+   * The published SCHEMA is deliberately not widened to advertise the name
+   * form: the schema states the target contract, while the reader is
+   * transitionally lenient. A producer validating against the schema is
+   * correctly told that names are not the shape to emit.
+   */
+  customActions?: ElementActionInfo[] | null;
   /**
    * Unique element ID within the registry.
    */
@@ -94,3 +141,72 @@ export interface UIBridgeElement {
    */
   visible?: boolean | null;
 }
+/**
+ * Information about a single custom (application-defined) action exposed by a
+ * UI Bridge **element**.
+ *
+ * The element-level twin of [`ComponentActionInfo`], and deliberately the same
+ * field vocabulary so a consumer that walks both action planes reads one shape,
+ * not two. One field is NOT carried over: `path`. A component action has a
+ * resolved per-action invocation path because the SDK annotates one
+ * (`/control/component/<componentId>/action/<actionId>`); an element action has
+ * no analogue — every element action is invoked through the single
+ * `/control/element/<elementId>/action` route with the action name in the body.
+ * A field nothing would ever populate is dead schema surface, so it is absent
+ * rather than perpetually `null`.
+ *
+ * ## Why this is an object rather than a name
+ *
+ * It exists so `effect` has somewhere to live. A bare list of action NAMES is
+ * unannotatable: there is no slot on a name for a safety class, so an
+ * element-level custom action could not declare itself `destructive` however
+ * much its author wanted to. That is not hypothetical — the runner exposes
+ * element custom actions that write raw bytes into a live agent PTY, and some
+ * of them act on a pane with no visible view.
+ *
+ * The wire projection is widened FIRST and the annotation lands on top of it.
+ * The reverse order ships an UNREACHABLE annotation, which is worse than an
+ * absent one: the author believes the delete button is marked, and the walker
+ * walks it anyway.
+ */
+export interface ElementActionInfo {
+  /**
+   * Longer description of what the action does.
+   */
+  description?: string | null;
+  /**
+   * Safety class of this action: `read`, `write` or `destructive`.
+   *
+   * **A safety annotation, not a hint.** An autonomous walk MUST NOT fire an
+   * action annotated `destructive`; that is the same exclusion the IR already
+   * applies to `destructive` transitions when generating auto-regressions.
+   * Author-declared, because only the app author knows that a particular
+   * custom action sends the keystrokes that end a session.
+   *
+   * Absent means **unclassified, not safe** — an action nobody has judged
+   * must be treated as unknown rather than as `read`. `skip_serializing_if`
+   * keeps an un-annotated action ABSENT on the wire rather than defaulting to
+   * a class nobody chose.
+   */
+  effect?: ("read" | "write" | "destructive") | null;
+  /**
+   * Unique action identifier within the element — the key the action is
+   * registered under, and the name `/control/element/<id>/action` is called
+   * with.
+   */
+  id: string;
+  /**
+   * Human-readable label.
+   */
+  label?: string | null;
+  /**
+   * Free-form declaration of the action's parameters, author-supplied on the
+   * SDK side and surfaced verbatim. Conventionally a small JSON Schema
+   * subset, but the SDK does not constrain the shape, so it is carried
+   * through untyped — the same treatment `ElementActionRequest::params` and
+   * `ComponentActionInfo::param_schema` get.
+   */
+  paramSchema?: {
+    [k: string]: unknown;
+  };
+}