api_binding_ui 3.1.0 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api_binding_ui",
-  "version": "3.1.0",
+  "version": "3.3.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",
@@ -66,4 +66,4 @@
       "optional": true
     }
   }
-}
+}

package/spec/FRAMEWORK.md

@@ -2,7 +2,7 @@
 
 Normative types: [`contract.ts`](../src/framework/contract.ts).
 
-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.
+The framework connects **UI components** to **documented API operations** at design time and turns the result into **plain code**. Binding lives in two files: `registry.json` (what exists: kinds and the screen → component → part tree) and `bindings.json` (how it is wired to the API). After design time the app holds only ordinary React Query hooks over an Orval client; no framework code, runtime or manifest ships.
 
 ---
 
@@ -11,7 +11,7 @@ The framework connects **UI components** to **documented API operations** at des
 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`.
+4. **Two files.** `registry.json` says what exists (kinds, screens, components); `bindings.json` says how it is wired (output settings, bindings). The studio writes only `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.
 
@@ -22,15 +22,15 @@ The framework connects **UI components** to **documented API operations** at des
 ```
 OpenAPI docs ──► Orval ──────────────► src/api/generated   (typed client)
      │
-     └──► api-binding studio ◄──► bindings.json ──► api-binding generate ──► src/api/screens (one hook per screen)
+     └──► api-binding studio ◄──► bindings.json (+ registry.json) ──► api-binding generate ──► src/api/screens (one hook per screen)
                                                                                │
                                           app components ── use<Screen>Api(state) ┘
 ```
 
 | Piece | What it is | Owned by |
 |---|---|---|
-| 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` |
+| Kinds | A component kind's slots, with JSON Schema shapes | Design system, in `registry.json` → `kinds` |
+| Screens and components | Every screen and component instance, by id | The app, in `registry.json` (a tree; nesting gives each part its parent) |
 | 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` |
@@ -160,8 +160,9 @@ Warnings: drafts, unconnected required body fields, and with `--src` every regis
 
 ## 10. Studio rules
 
-- Runs from the Vite dev plugin (`api_binding_ui/vite`, serve only) or the CLI (`api-binding studio`). Either server reads and writes `bindings.json` and fetches the docs server-side, so the browser needs no CORS access.
-- The dev plugin's floating button opens the studio over the app on the screen shown: the screen most visible `data-component-id` values belong to, within the topmost open dialog if it has any. Alt+click opens it on one component. Nothing reaches a build.
+- Runs from the Vite dev plugin (`api_binding_ui/vite`, serve only) or the CLI (`api-binding studio`). Either server reads `registry.json`, reads and writes `bindings.json`, and fetches the docs server-side, so the browser needs no CORS access.
+- Under the Vite plugin every save regenerates the screen hooks, so a confirmed binding is live in the running app after the save. Vite does not watch `bindings.json`. On start it also generates the API client (the app's `orval.config.ts`) and the hooks, so a project needs no committed generated code.
+- The dev plugin's floating button opens the studio over the app on the screen shown: the screen most `data-component-id` values the user can see belong to; a component covered by any layer above it does not count. Alt+click opens it on one component. Nothing reaches a build.
 - 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.
@@ -170,7 +171,7 @@ Warnings: drafts, unconnected required body fields, and with `--src` every regis
 
 ## 11. Conformance rules for an app
 
-1. Every bindable component has a `componentId` in the format above, registered in `bindings.json`.
+1. Every bindable component has a `componentId` in the format above, registered in `registry.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.