api_binding_ui 2.0.1 → 3.0.0

package/package.json

@@ -1,53 +1,65 @@
-{
-  "name": "api_binding_ui",
-  "version": "2.0.1",
-  "description": "API binding framework: bind any UI component to documented APIs at design time, run the bindings in production.",
-  "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./studio": {
-      "types": "./dist/studio/index.d.ts",
-      "import": "./dist/studio/index.js"
-    },
-    "./studio.css": "./dist/studio/index.css",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "dist",
-    "spec/FRAMEWORK.md",
-    "README.md",
-    "SKILL.md"
-  ],
-  "sideEffects": [
-    "**/*.css"
-  ],
-  "scripts": {
-    "dev": "bun --port=5174 ./index.html",
-    "build": "rm -rf dist && bun build src/index.ts src/studio/index.ts --outdir dist --root src --target browser --splitting --sourcemap=linked --external react --external react-dom --external react/jsx-runtime --external yaml && node ./node_modules/typescript/bin/tsc -p tsconfig.build.json",
-    "typecheck": "node ./node_modules/typescript/bin/tsc --noEmit -p tsconfig.json",
-    "test": "bun test",
-    "prepublishOnly": "bun run typecheck && bun test && bun run build"
-  },
-  "peerDependencies": {
-    "react": ">=18.0.0",
-    "react-dom": ">=18.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.13.0",
-    "@types/react": "^19.2.0",
-    "@types/react-dom": "^19.2.0",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
-    "typescript": "^5.8.0",
-    "vitest": "^3.0.0"
-  },
-  "dependencies": {
-    "yaml": "^2.8.1"
-  }
-}
+{
+  "name": "api_binding_ui",
+  "version": "3.0.0",
+  "description": "Design-time API binding: register screen components, bind them to documented APIs in a studio, and generate plain React Query hooks over an Orval client. Nothing ships in the app.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./studio": {
+      "types": "./dist/studio/index.d.ts",
+      "import": "./dist/studio/index.js"
+    },
+    "./studio.css": "./dist/studio/index.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "spec/FRAMEWORK.md",
+    "README.md",
+    "SKILL.md"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "scripts": {
+    "dev": "bun run build:app && node dist/cli.js studio src/dev/sample/bindings.json",
+    "build:app": "rm -rf dist/app && bun build ./index.html --outdir dist/app --minify",
+    "build": "rm -rf dist && bun build src/index.ts src/studio/index.ts --outdir dist --root src --target browser --splitting --sourcemap=linked --external react --external react-dom --external react/jsx-runtime --external yaml && bun build src/cli/cli.ts --outfile dist/cli.js --target node --external yaml --banner '#!/usr/bin/env node' && bun run build:app && node ./node_modules/typescript/bin/tsc -p tsconfig.build.json",
+    "typecheck": "node ./node_modules/typescript/bin/tsc --noEmit -p tsconfig.json",
+    "test": "bun test",
+    "prepublishOnly": "bun run typecheck && bun test && bun run build"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "yaml": "^2.8.1"
+  },
+  "bin": {
+    "api-binding": "dist/cli.js"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  }
+}

package/spec/FRAMEWORK.md

@@ -1,271 +1,176 @@
-# API Binding Framework — v1 (draft)
+# API Binding Framework — v3
 
-Status: draft for review. Normative types: [`contract.ts`](./contract.ts).
+Normative types: [`contract.ts`](../src/framework/contract.ts).
 
-This framework connects **UI components** to **documented API operations** during the design phase, and produces a reviewed, versioned **binding manifest** for every screen. Any product can adopt it. It contains no knowledge of any component kind, product, operation or field: all of that arrives as data or through registration.
+The framework connects **UI components** to **documented API operations** at design time and turns the result into **plain code**. Everything about binding lives in one file, `bindings.json`. After design time the app holds only ordinary React Query hooks over an Orval client; no framework code, runtime or manifest ships.
 
 ---
 
 ## 1. Principles
 
-1. **Nothing concrete in the framework.** No component kinds, product names, operation ids, field names or vocabularies are written into framework code. If something has to be known, it is declared as data (descriptor, registry entry, catalog, glossary) or registered as an extension.
-2. **The API docs are the only source of operations.** The catalog is generated from the published OpenAPI documents. Nothing is supplied by the app instead: no local hooks, hardcoded option lists or free-text overrides.
-3. **UI first.** The unit of work is a screen and its components. APIs are attached to component slots, not the other way round.
-4. **Components describe themselves.** Every bindable component ships a descriptor stating its slots. A component built next year works with the same studio, the same manifest and the same runtime, unchanged.
-5. **Types flow through bindings.** The shape of a selection, a row or a dialog's context is derived from what the source slot is bound to, never typed in by hand.
-6. **Design-time and runtime are separate.** The studio never ships to production. The runtime reads manifests only.
-7. **Every contract is versioned.** Descriptors, registry, catalog and manifest each carry a version, and changes are detected, not discovered in production.
+1. **Nothing concrete in the framework.** Component kinds, products, operations and fields arrive as data: kinds and the registry in the bindings file, operations from the OpenAPI docs.
+2. **The API docs are the only source of operations.** No local hooks, hardcoded option lists or free-text overrides.
+3. **UI first.** The unit of work is a screen and its components; APIs attach to component slots.
+4. **One file.** Kinds, screens, components, bindings and output settings are all in `bindings.json`.
+5. **No trace at run time.** The generator writes plain hooks; the app never imports this package.
+6. **Deterministic.** The same file and docs always produce the same code. Generated files carry an `@generated` mark and are never edited by hand.
 
 ---
 
-## 2. The pieces and who owns them
-
-| Piece | What it is | Owned by | Format |
-|---|---|---|---|
-| Component descriptor | A kind's slots, with JSON Schema shapes | Component library (design system) | `ComponentDescriptor` |
-| Screen registry | Every screen in the app, with its component instances | Each product | `ScreenRegistry` (JSON) |
-| Catalog | Normalized operations from the API docs | Generated from OpenAPI with `catalogFromOpenApi` | `Catalog` (JSON) |
-| Binding manifest | Which operation or expression feeds each slot | Designers in the studio, reviewed by engineers | `BindingManifest` (JSON, one per screen) |
-| Extensions | Transforms, context providers, matchers, glossaries, persistence | Framework defaults + products | `FrameworkRegistry` |
-| Studio | Design-time editor that reads all of the above | This package | UI, design mode only |
-| Runtime | Executes manifests in the app | This package | Small library, production |
+## 2. The pieces
 
 ```
-OpenAPI docs ──► Catalog ─┐
-Descriptors ──────────────┼──► Studio ──► Manifests (repo) ──► Runtime (production)
-Screen registry ──────────┘
+OpenAPI docs ──► Orval ──────────────► src/api/generated   (typed client)
+     │
+     └──► api-binding studio ◄──► bindings.json ──► api-binding generate ──► src/api/screens (one hook per screen)
+                                                                               │
+                                          app components ── use<Screen>Api(state) ┘
 ```
 
----
-
-## 3. Component descriptors
-
-A descriptor is published once per component kind, next to the component, by whoever builds the component. The framework only understands three slot **roles**:
-
-| Role | Meaning | Bound to |
+| Piece | What it is | Owned by |
 |---|---|---|
-| `consume` | The component needs data | An operation (via request + response selection) or an expression |
-| `produce` | The component exposes data | Nothing; it is a **source** others can read |
-| `trigger` | The component emits an event | An ordered list of steps |
+| Kinds | A component kind's slots, with JSON Schema shapes | Design system, in `bindings.json` → `kinds` |
+| Screens and components | Every screen and component instance, by id | The app, in `bindings.json` |
+| Bindings | Which operation or value feeds each slot | Designers in the studio, reviewed by engineers |
+| Orval client | Typed functions per operation | Generated by Orval from the same docs |
+| Screen hooks | `use<Screen>Api(state)` per screen | Generated by `api-binding generate` |
 
-Each slot carries a JSON Schema (`schema`) and an optional `many`. That is all the studio needs to render an editor, propose matches and validate.
-
-**Scoped slots.** A consume slot can be evaluated per item of a parent slot (`scope.parentSlot`). Inside it, `$item` is the parent's current item. This covers cells in rows, items in a list, cards in a lane, without the framework knowing what a row, list or lane is.
-
-**Feeding requests.** A consume slot can name produce slots of the same component in `feeds` (for example, paging or sorting state). The studio offers them as sources when mapping that slot's request.
+---
 
-### Illustrations (not part of the framework)
+## 3. Ids
 
-These show three unrelated kinds expressed with the same vocabulary. Names are examples.
+One namespace for screens and components, used everywhere: in `componentId` props, in the file and in expressions.
 
-```jsonc
-// A data grid
-{ "kind": "example-ds/grid", "version": 1, "label": "Grid",
-  "children": { "scopedTo": "rows" },
-  "slots": [
-    { "id": "rows",      "role": "consume", "many": true, "required": true, "label": "Rows",
-      "schema": { "type": "object" }, "feeds": ["page", "sort", "filter"] },
-    { "id": "total",     "role": "consume", "label": "Total", "schema": { "type": "integer" } },
-    { "id": "page",      "role": "produce", "label": "Page", "schema": { "type": "object", "properties": { "offset": { "type": "integer" }, "limit": { "type": "integer" } } } },
-    { "id": "sort",      "role": "produce", "label": "Sort", "schema": { "type": "object", "properties": { "field": { "type": "string" }, "direction": { "enum": ["asc", "desc"] } } } },
-    { "id": "filter",    "role": "produce", "label": "Filter", "schema": { "type": "object" } },
-    { "id": "selection", "role": "produce", "many": true, "label": "Selected rows", "schema": { "$ref": "#slot/rows" } },
-    { "id": "rowClick",  "role": "trigger", "label": "Row clicked", "schema": { "$ref": "#slot/rows" } }
-  ] }
-
-// A single-choice input
-{ "kind": "example-ds/select", "version": 1, "label": "Dropdown",
-  "slots": [
-    { "id": "options", "role": "consume", "many": true, "label": "Options",
-      "schema": { "type": "object", "required": ["value", "label"], "properties": { "value": {}, "label": { "type": "string" } } } },
-    { "id": "selected", "role": "produce", "label": "Selected option", "schema": { "$ref": "#slot/options" } },
-    { "id": "change",   "role": "trigger", "label": "Changed", "schema": { "$ref": "#slot/options" } }
-  ] }
-
-// A dropdown publishes the whole chosen option, not only its display value: every field the options API
-// returns (an id, a code, a name) is then available as a separate, correctly typed value.
-
-// A component that does not exist yet
-{ "kind": "example-ds/timeline", "version": 1, "label": "Timeline",
-  "slots": [
-    { "id": "events", "role": "consume", "many": true, "label": "Events",
-      "schema": { "type": "object", "required": ["at", "title"], "properties": { "at": { "type": "string", "format": "date-time" }, "title": { "type": "string" }, "detail": { "type": "string" } } } },
-    { "id": "eventClick", "role": "trigger", "label": "Event clicked", "schema": { "$ref": "#slot/events" } }
-  ] }
+```
+<product>.<screen>[.<sub-screen>…].<component>[.<part>…]
+collections.worklist                         screen
+collections.worklist.add-notes               sub-screen (a dialog over the worklist)
+collections.worklist.grid                    component on collections.worklist
+collections.worklist.grid.column.customer-name
+collections.worklist.grid.row.add-notes
+collections.worklist.add-notes.notes-type    component on collections.worklist.add-notes
 ```
 
-`"$ref": "#slot/<id>"` means "the same shape as that slot after binding". This is how a grid's selection gets the row shape of whatever operation feeds its rows, and how a dropdown's selected option gets the fields of the operation that feeds its options. Until that slot is bound, the shape is unknown and the studio offers nothing from it; it shows which slot to connect first.
-
----
-
-## 4. Screen registry
-
-The registry lists the screens that exist in the app, and only those. It is the studio's inventory, so thousands of screens can be bound without opening the app.
-
-- Each screen ships its registry entry next to its code (a JSON file or an exported constant). The app's build collects the entries into one registry file.
-- A screen that is not in the app has no entry. Nothing is listed ahead of time.
-- Every component in an entry must have a registered descriptor. An unknown kind fails validation at build time, so the studio never shows a component it cannot bind.
-- `context` declares what a screen receives from outside. Its shape is either a schema or a reference to another screen's produce slot (`shape.from`), so a dialog opened from a grid toolbar automatically knows the selected rows' fields.
-- `parent` groups a dialog or drawer under the screen it appears over, for studio navigation only. How it opens and closes is the app's own UI code.
+- Segments are lowercase kebab-case (`[a-z0-9-]`), joined by dots: `^[a-z][a-z0-9-]*(\.[a-z0-9-]+)+$`.
+- A component belongs to the **longest** registered screen id that prefixes it. A screen's parent is the longest other screen id that prefixes it. Navigation is built from this; there is no `path` or `parent` to maintain.
+- A component id may not equal a screen id (it would capture that screen's components).
+- Ids are stable: renaming one orphans its bindings. They never depend on labels.
+- In the app, each component gets `componentId="<id>"`; design-system components render it as `data-component-id`.
 
 ---
 
-## 5. Catalog
+## 4. Kinds and slots
 
-`api-binding catalog pull <url-or-file>` normalizes one or more OpenAPI 3.x documents into a `Catalog`:
+A kind declares slots with one of three **roles**:
 
-- Every operation, with parameters as request pointers (`/path/…`, `/query/…`, `/header/…`, `/body/…`), body schema and response schemas.
-- `intent` comes from HTTP semantics (safe methods are reads) unless the docs declare it with an extension. It is never inferred from names.
-- All `x-*` extensions are kept verbatim, so new docs metadata reaches matchers without a framework change.
-- A content hash pins the catalog. Manifests record the hash they were made with.
+| Role | Meaning | Bound to |
+|---|---|---|
+| `consume` | The component needs data | An operation (request + response selection) or an expression |
+| `produce` | The component exposes data | Nothing; a source others read |
+| `trigger` | The component emits an event | Ordered API call steps, or "no API" |
 
-List locations in responses are discovered from schemas (any array of objects is a candidate selector). Envelope shapes are never assumed.
+- `scope.parentSlot`: the slot is evaluated per item of the parent's slot (a cell in a row, an action on a row); `$item` is that item.
+- `feeds`: produce slots of the same component offered as request sources (paging, sorting).
+- `"$ref": "#slot/<id>"`: the same shape as that slot after binding (a grid's selection has the shape of its rows).
 
 ---
 
-## 6. Binding manifest
+## 5. The bindings file
 
-One JSON file per screen in the product repository (for example `bindings/<screen-id>.binding.json`). It references only: bindIds and slot ids from the registry and descriptors, operation ids from the catalog, and expressions.
+```jsonc
+{
+  "version": 3,
+  "openapi": "https://apidocs.example.com/index.yaml",   // or a path next to this file
+  "output": { "dir": "src/api/screens", "client": "@/api/generated" },
+  "kinds": [ /* ComponentDescriptor */ ],
+  "screens": [ { "id": "collections.worklist.add-notes", "label": "Add Notes",
+                 "context": [ { "id": "selection", "label": "Selected rows", "many": true,
+                                "shape": { "from": { "screen": "collections.worklist", "component": "collections.worklist.grid", "slot": "selection" } } } ] } ],
+  "components": [ { "id": "collections.worklist.add-notes.notes-type", "kind": "hr-ds/select", "label": "Notes Type" } ],
+  "bindings": [ /* SlotBinding */ ]
+}
+```
 
 | Slot role | Binding type | Contents |
 |---|---|---|
-| consume | `operation` | operation, request mapping (pointer → expression), response `select`, optional `map` to the slot's properties, load policy |
-| consume | `expression` | a single expression (scoped item field, another component's produce slot, context) |
-| trigger | `steps` | ordered API `call` steps; a call may run `forEach` over a list |
+| consume | `operation` | operation, request mapping (pointer → expression), response `select`, optional `map`, `load` |
+| consume | `expression` | one expression |
+| trigger | `steps` | ordered `call` steps; a step may run `forEach` over a list; `onError: stop \| continue` |
 | trigger | `none` | reviewed: this event calls no API |
-| produce | — | never bound; produce slots are sources |
-
-Bindings describe API calls and nothing else. Opening and closing screens, navigation, reloading after a save and every other UI behaviour belong to the app's code, never to a manifest.
 
-Every binding records `origin` (manual or suggested) and `state` (draft or confirmed). Only confirmed bindings run in production.
+Only `confirmed` bindings are generated; drafts are reported as warnings. Bindings describe API calls only: opening, closing, navigation, toasts and reloads are app code.
 
 ---
 
-## 7. Expressions
-
-One grammar for every source. Nothing outside it is allowed.
+## 6. Expressions
 
 | Form | Resolves to |
 |---|---|
-| `<bindId>.<slot>` | A produce slot of a component on this screen, e.g. `subject.value`, `grid.selection`, `status.selected` |
-| `<bindId>.<slot>.<path>` | A property inside it |
+| `<componentId>:<slot>[.path]` | A produce slot on the same screen, e.g. `collections.worklist.add-notes.subject:value` |
 | `<expr>[*].<path>` | A property of every item, as a list |
-| `$item.<path>` | The current item in a scoped slot or `forEach` |
-| `$context.<id>.<path>` | A value declared in the screen's `context` |
-| `$<provider>.<path>` | A registered context provider |
-| `$steps.<stepId>.response.<path>` | The response of an earlier `call` step |
-| `<expr> \| <transform>(<args>)` | A registered transform |
+| `$item[.path]` | The current item: a scoped slot's item, a `forEach` item, or the trigger's payload |
+| `$context.<id>[.path]` | A value declared in the screen's `context` |
+| `$steps.<stepId>.response[.path]` | The response of an earlier step |
 
-Literal values are allowed only when the target schema defines them (`enum`, `const` or `default`). There is no free-text source.
+`:` ends a component id, so ids can contain dots. Nothing outside this grammar is valid.
 
 ---
 
-## 8. Suggestions
+## 7. Generated code
 
-The studio ranks **all** catalog operations for each slot and shows the best ones first. The user can always choose any operation. Ranking is done by registered `Matcher`s, combined by weight. The default matchers use only metadata already present in the inputs:
+`api-binding generate` writes into `output.dir`:
 
-| Matcher | Signal |
-|---|---|
-| Shape | Compatibility between the slot's schema and the operation's response (consume) or request (trigger), including `many` and scalar types |
-| Intent | Slot role and `hints.intents` against the operation's `intent` |
-| Names | Token similarity between screen, component and slot labels and the operation's summary, tags and description |
-| Glossary | Synonym groups from registered glossaries (data files per product) |
-| Fields | For request and `map` entries: name and type similarity between available sources and target fields |
+- `screen-helpers.ts`: the few helpers the hooks share (React Query only).
+- `<screen id>.ts` per screen: `<Screen>State`, `<Screen>Api` and `use<Screen>Api(state)`.
+- `index.ts`: re-exports.
 
-Rules for matchers: no product words in code, every score comes with plain reasons, and proposals stay `origin: "suggested"` until a person confirms them.
+**The signature comes from the registry, the body from the bindings.** `<Screen>State` has one optional entry per component that produces values; `<Screen>Api` has one entry per consume and trigger slot. Changing bindings never changes either type, so call sites stay put. Adding or removing components does, and `tsc` points at every call site to update.
 
----
-
-## 9. Validation
-
-The studio and CI (a script calling `validateRegistry` and `validateBindings`) apply the same rules. All are generic:
-
-- A `required` slot is unbound.
-- A binding refers to a bindId, slot, operation or descriptor version that no longer exists.
-- Schema incompatibility between a source expression and its target (type, `many` vs single, required request fields unmapped).
-- An expression uses a source not available on this screen.
-- A literal is not defined by the target schema.
-- The catalog hash changed: each affected binding is listed with what changed (field removed, renamed or newly required).
-
----
-
-## 10. Studio rules
-
-The studio renders entirely from descriptors, registry, catalog and manifest:
+| Slot | Returns | When unbound |
+|---|---|---|
+| consume | `Data<T>`: `{ bound, data, loading, error }` | `bound: false`; keep the UI's own value |
+| consume, scoped | `Cell<T>`: `{ bound, read(item) }` | `read` returns `undefined` |
+| trigger | `Action`: `{ bound, run(payload?), running, error }` | `run` resolves at once |
 
-- Navigation comes from `ScreenEntry.path` and `parent`. It scales to any number of screens.
-- Component lists come from `ScreenEntry.components`. Icons come from descriptors.
-- There are exactly three slot editors, chosen by role, and their forms are generated from the slot's schema. A new kind never needs studio code.
-- Every consume and trigger slot offers the full catalog in a searchable picker, with matcher suggestions on top.
-- The studio shows only what validates. A component with an unknown kind, or a binding that points at an operation no longer in the catalog, is reported by validation and kept out of the studio until it is fixed.
+- Queries call the Orval function for the operation: path params in path order, then the body, then the query params object, then fetch options (headers). A query is enabled only when every required input has a value; `load: { everySeconds }` polls.
+- Actions run steps in order. A failed call rejects `run` (`stop`) or is collected and rejected after the rest run (`continue`).
+- Responses are unwrapped from Orval's `{ data, status, headers }`; a non-2xx status throws `ApiError`.
 
 ---
 
-## 11. Runtime
-
-Entry `api_binding_ui`. Production-safe: it contains no studio code and no styles.
-
-```tsx
-<BindingProvider catalog={catalog} manifests={manifests} fetcher={fetcher} transforms={…} providers={…}>
-  <BindingScreen id="collections.worklist.add-notes" context={{ selection: selectedRows }}>
-    …
-  </BindingScreen>
-</BindingProvider>
-```
-
-| Hook | Slot role | Returns |
-|---|---|---|
-| `useSlot(bindId, slot)` | consume | `{ status, data, error, reload }`; status is `unbound`, `waiting` (a required input has no value yet), `loading`, `ready` or `error` |
-| `useCell(bindId, slot)` | scoped consume | `(item) => value` for one row or item |
-| `useProduce(bindId, slot, value)` | produce | publishes the component's current value to the screen |
-| `useTrigger(bindId, slot)` | trigger | `{ bound, running, run(item?) }`; `run` performs the API calls and returns each step's outcome |
+## 8. Suggestions
 
-- Only **confirmed** bindings run. Drafts exist only in the studio.
-- Requests are built from request pointers and sent through the host's `fetcher`; base URL, authentication and error display stay in the app.
-- A component re-renders only when the values its own binding reads change. Identical requests on one screen share one call.
-- Without a confirmed binding a consume slot is `unbound` and a trigger has `bound: false`. What the component shows or does then is the app's decision.
-- Bindings never open, close, navigate or reload anything. After `run()` resolves, the app decides what happens next (for example close a dialog and call `reload()` on a grid).
+The studio ranks **all** operations for each slot and shows the best first; any operation can be chosen. Ranking uses metadata only: shape compatibility, intent, name similarity, glossary synonyms. Request fields are proposed from the values the screen has (produce slots, context, earlier steps, the current item), ranked by name and type. Proposals stay `origin: "suggested"` until a person confirms them.
 
 ---
 
-## 12. Design-time integration
-
-Entry `api_binding_ui/studio` (plus `api_binding_ui/studio.css`). Import it only from design-time code so production bundles never contain it.
+## 9. Validation
 
-- The app renders `<BindingWidget framework={{ descriptors, registry, transforms, providers }} />` once, inside `BindingProvider`, in design mode only. It is a floating button that opens the studio in a modal over the app, on the most recently shown `BindingScreen` (an open dialog wins over its page). Views that stay mounted while hidden (inactive tabs) are wrapped in `<BindingActive value={isVisible}>` so their screens are skipped. When the studio closes, the runtime reloads the saved manifests of mounted screens, so edits apply without a page reload.
-- `<BindingStudio>` is the same studio as a plain component, for hosts that mount it on their own page.
-- The studio loads the catalog from the published docs (`docsUrl`, default `https://apidocs.highradius.com/documentation-ui/index.yaml`; JSON or YAML; products from `x-tagGroups`). Each user can change the URL in Settings. A `catalog` passed in `framework` is used instead.
-- Settings also download and import manifests as JSON, so bindings made in the studio can be committed with the app.
-- The widget saves manifests through `BindingProvider persistence` (browser storage by default), so the app runs them immediately. Committed manifests come from Settings → Download.
+`api-binding generate` fails, and writes nothing, on any error:
 
----
+- an id that breaks the format, is duplicated, or clashes with a screen id; a component under no screen
+- an unknown kind, or a parent that is not registered
+- an expression reading a slot that is not produced on the screen, an undeclared context, a later step, or `$item` where there is none
+- an operation not in the docs, a request input the operation does not have, an unconnected path parameter
+- two components whose names become the same TypeScript key
 
-## 13. Versioning
-
-| Contract | Version field | On change |
-|---|---|---|
-| Descriptor | `version` per kind | Manifests record `kinds`; the studio offers a migration when a kind's version rises |
-| Registry | `registryVersion` | Bumped when the shape changes; a migration ships with the package version that changes it |
-| Catalog | `catalogVersion`, `hash` | bindings to operations no longer in the catalog are reported by validation and hidden in the studio |
-| Manifest | `manifestVersion` | Bumped when the shape changes; a migration ships with the package version that changes it |
+Warnings: drafts, unconnected required body fields, and with `--src` every registered id missing from the source (and every `componentId` literal not registered). `--check` exits 1 when generated files are out of date.
 
 ---
 
-## 14. Conformance rules for an app (for example, an app built with Lovable)
+## 10. Studio rules
 
-1. Every interactive or data-showing component comes from a library that publishes a descriptor for its kind.
-2. Every component instance has a stable `bindId`, unique within its screen and independent of its label.
-3. Every screen is wrapped in `BindingScreen` with a stable screen id and declares its `context`.
-4. Components get data and call APIs only through their slots. No direct API calls, no hardcoded option lists, no local data hooks in screens. Opening, closing and navigation stay in the app's UI code.
-5. Dialogs and drawers are separate screens with `parent` set to the screen they appear over.
-6. Manifests are committed to the repository and reviewed like code.
-7. The catalog is regenerated from the docs, never edited by hand.
+- Runs locally from the CLI (`api-binding studio`); it reads and writes `bindings.json` and fetches the docs server-side, so the browser needs no CORS access.
+- Navigation and component lists come from the ids. Icons come from kinds.
+- Three slot editors, one per role, generated from slot schemas. A new kind never needs studio code.
+- Shows only what validates.
 
 ---
 
-## 15. Out of scope for the framework
+## 11. Conformance rules for an app
 
-- Any list of component kinds or slots (they belong to descriptors).
-- Any product, module, operation or field name (they belong to the registry, catalog and manifests).
-- Any vocabulary or naming rule (it belongs to glossaries and docs extensions).
-- Business behavior that is not expressed as slots and steps.
+1. Every bindable component has a `componentId` in the format above, registered in `bindings.json`.
+2. Each screen calls its generated `use<Screen>Api(state)` once, passes what its components produce and what it was opened with, and renders `bound ? data : <its own value>`.
+3. No direct API calls in screens other than through generated hooks; no hardcoded data an API should provide.
+4. Opening, closing, navigation, toasts and reloads stay in the app's UI code.
+5. Orval output and screen hooks are regenerated, never edited by hand.

package/dist/framework/runner.d.ts

@@ -1,36 +0,0 @@
-/** Builds requests, reads responses and runs trigger steps. */
-import type { CatalogOperation, OperationConsumeBinding, Step } from "./contract";
-import { type Scope } from "./expr";
-export interface HttpRequest {
-    method: string;
-    /** Path with parameters filled in, e.g. "/cls/v1/notes/42". */
-    path: string;
-    query: Record<string, string>;
-    headers: Record<string, string>;
-    body?: unknown;
-}
-/** Sends a request. Supplied by the host (base URL, auth, errors). */
-export type Fetcher = (request: HttpRequest, operation: CatalogOperation) => Promise<unknown>;
-export declare class BindingError extends Error {
-    readonly detail?: unknown | undefined;
-    constructor(message: string, detail?: unknown | undefined);
-}
-export declare function buildRequest(op: CatalogOperation, request: Record<string, string>, scope: Scope): HttpRequest;
-/** Identical requests share a key, and so one fetch. */
-export declare const requestKey: (r: HttpRequest) => string;
-/** "$", "$.a.b" or "$.a.items[*]" applied to a response. */
-export declare function select(response: unknown, selector: string): unknown;
-/**
- * Applies a consume binding's `map` to each item. Mapped properties are added to the item, not substituted for it,
- * so a produce slot shaped by this slot (a dropdown's selected option) keeps every field the API returned.
- */
-export declare function mapItems(data: unknown, binding: OperationConsumeBinding, scope: Scope): unknown;
-export declare function runConsume(binding: OperationConsumeBinding, op: CatalogOperation, scope: Scope, fetcher: Fetcher): Promise<unknown>;
-export interface StepOutcome {
-    step: string;
-    ok: boolean;
-    response?: unknown;
-    error?: unknown;
-}
-/** Runs call steps in order. `forEach` runs a call once per item; `onError: "stop"` ends the run at the first failure. */
-export declare function runSteps(steps: Step[], operations: Map<string, CatalogOperation>, scope: Scope, fetcher: Fetcher): Promise<StepOutcome[]>;