api_binding_ui 3.1.0 → 3.3.0

package/dist/vite.js

@@ -1,12 +1,21 @@
 // src/vite/plugin.ts
-import path2 from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import path4 from "node:path";
 
 // src/server/handler.ts
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+// src/framework/names.ts
+function humanize(id) {
+  const s = id.replace(/^\$\.?/, "").replace(/\[\*\]/g, "").split(/[./]/).filter(Boolean).pop() ?? id;
+  const w = s.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ").toLowerCase().trim();
+  return w ? w[0].toUpperCase() + w.slice(1) : id;
+}
+
 // src/framework/file.ts
+var ID = /^[a-z][a-z0-9-]*(\.[a-z0-9-]+)+$/;
 var BINDING_TYPES = new Set(["operation", "expression", "steps", "none"]);
 function parseBindingsFile(text) {
   let data;
@@ -15,6 +24,9 @@ function parseBindingsFile(text) {
   } catch {
     throw new Error("The bindings file is not valid JSON.");
   }
+  return checkBindingsFile(data);
+}
+function checkBindingsFile(data) {
   const f = data;
   if (!f || typeof f !== "object")
     throw new Error("The bindings file must be a JSON object.");
@@ -34,6 +46,100 @@ function parseBindingsFile(text) {
     throw new Error(`"output" needs "dir" and "client".`);
   return f;
 }
+var REGISTRY_KEYS = ["kinds", "screens", "components"];
+function parseRegistry(text) {
+  let r;
+  try {
+    r = JSON.parse(text);
+  } catch {
+    throw new Error("The registry file is not valid JSON.");
+  }
+  if (!r || r.version !== 1)
+    throw new Error(`The registry file must have "version": 1.`);
+  if (!Array.isArray(r.kinds) || !Array.isArray(r.screens))
+    throw new Error(`The registry file needs "kinds" and "screens" lists.`);
+  const screens = [];
+  const components = [];
+  const under = (id, owner, what) => {
+    if (typeof id !== "string" || !id)
+      throw new Error(`A ${what} in the registry has no "id".`);
+    if (owner && !id.startsWith(owner + "."))
+      throw new Error(`"${id}" must start with "${owner}.", the id it is nested under.`);
+  };
+  const node = (n, owner, parent) => {
+    under(n.id, owner, "component");
+    if (typeof n.kind !== "string" || typeof n.label !== "string")
+      throw new Error(`"${n.id}" needs "kind" and "label".`);
+    const { children, ...c } = n;
+    components.push(parent ? { ...c, parent } : c);
+    for (const ch of children ?? [])
+      node(ch, n.id, n.id);
+  };
+  const screen = (s, owner) => {
+    under(s.id, owner, "screen");
+    const { components: cs, screens: subs, ...rest } = s;
+    screens.push(rest);
+    for (const c of cs ?? [])
+      node(c, s.id);
+    for (const sub of subs ?? [])
+      screen(sub, s.id);
+  };
+  for (const s of r.screens)
+    screen(s);
+  return { kinds: r.kinds, screens, components };
+}
+function screenOf(id, screens) {
+  let best;
+  for (const s of screens)
+    if (id.startsWith(s + ".") && (!best || s.length > best.length))
+      best = s;
+  return best;
+}
+function productLabel(seg, catalog) {
+  const names = new Set(catalog.operations.map((o) => o.product).filter((p) => !!p));
+  return [...names].find((n) => n.toLowerCase().replace(/[^a-z0-9]+/g, "-") === seg) ?? humanize(seg);
+}
+function fromFile(file, catalog) {
+  const issues = [];
+  const ids = file.screens.map((s) => s.id);
+  const screens = file.screens.map((s) => ({
+    id: s.id,
+    label: s.label,
+    description: s.description,
+    context: s.context ?? [],
+    components: [],
+    path: [productLabel(s.id.split(".")[0], catalog)],
+    parent: screenOf(s.id, ids)
+  }));
+  const byId = new Map(screens.map((s) => [s.id, s]));
+  const screenIds = new Set(ids);
+  for (const c of file.components) {
+    if (screenIds.has(c.id)) {
+      issues.push({ severity: "error", screen: c.id, component: c.id, code: "registry.id-clash", message: `"${c.id}" is both a screen and a component id.` });
+      continue;
+    }
+    const s = screenOf(c.id, ids);
+    if (!s) {
+      issues.push({ severity: "error", screen: "", component: c.id, code: "registry.no-screen", message: `"${c.id}" starts with no registered screen id.` });
+      continue;
+    }
+    byId.get(s).components.push({ bindId: c.id, kind: c.kind, label: c.label, parent: c.parent, info: c.info });
+  }
+  const index = {};
+  for (const b of file.bindings) {
+    const s = screenOf(b.component, ids);
+    if (!s) {
+      issues.push({ severity: "error", screen: "", component: b.component, slot: b.slot, code: "binding.no-screen", message: `Binding for "${b.component}" fits no screen.` });
+      continue;
+    }
+    (index[s] ??= []).push(b);
+  }
+  return {
+    fw: { descriptors: file.kinds, registry: { registryVersion: 1, screens }, catalog, glossaries: file.glossaries },
+    index,
+    issues
+  };
+}
 
 // src/server/handler.ts
 var TYPES = { ".html": "text/html; charset=utf-8", ".js": "text/javascript", ".css": "text/css", ".svg": "image/svg+xml", ".map": "application/json", ".woff2": "font/woff2" };
@@ -52,6 +158,30 @@ async function readDocs(src, base) {
     throw new Error(`"${src}" is not a .yaml, .yml or .json file.`);
   return fs.readFile(path.resolve(base, src), "utf8");
 }
+async function readBindings(file) {
+  const text = await fs.readFile(file, "utf8");
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    throw new Error("The bindings file is not valid JSON.");
+  }
+  if (typeof raw?.registry !== "string")
+    return parseBindingsFile(text);
+  const registry = parseRegistry(await fs.readFile(path.resolve(path.dirname(file), raw.registry), "utf8"));
+  return checkBindingsFile({ ...raw, ...registry });
+}
+async function saveBindings(file, merged) {
+  let out = merged;
+  if (merged.registry) {
+    const rest = { ...merged };
+    for (const k of REGISTRY_KEYS)
+      delete rest[k];
+    out = rest;
+  }
+  await writeFileAtomic(file, JSON.stringify(out, null, 2) + `
+`);
+}
 async function writeFileAtomic(file, text) {
   const tmp = `${file}.${process.pid}.tmp`;
   await fs.writeFile(tmp, text, "utf8");
@@ -71,7 +201,7 @@ async function readBody(req, limit = 20 * 1024 * 1024) {
 function send(res, status, body, type = "text/plain; charset=utf-8") {
   res.writeHead(status, { "Content-Type": type, "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" }).end(body);
 }
-function createStudioHandler({ file, prefix, allowed }) {
+function createStudioHandler({ file, prefix, allowed, onSave }) {
   const base = path.dirname(file);
   return async (req, res) => {
     const url = new URL(req.url ?? "/", "http://local");
@@ -89,17 +219,18 @@ function createStudioHandler({ file, prefix, allowed }) {
       }
       if (rel === "/api/bindings") {
         if (req.method === "GET")
-          send(res, 200, await fs.readFile(file, "utf8"), "application/json");
+          send(res, 200, JSON.stringify(await readBindings(file)), "application/json");
         else if (req.method === "PUT") {
-          const text = await readBody(req);
+          let merged;
           try {
-            parseBindingsFile(text);
+            merged = parseBindingsFile(await readBody(req));
           } catch (e) {
             send(res, 400, e.message);
             return true;
           }
-          await writeFileAtomic(file, text);
+          await saveBindings(file, merged);
           send(res, 204, "");
+          onSave?.();
         } else
           send(res, 405, "Method not allowed.");
         return true;
@@ -139,6 +270,750 @@ function createStudioHandler({ file, prefix, allowed }) {
   };
 }
 
+// src/codegen/write.ts
+import { promises as fs3 } from "node:fs";
+import path3 from "node:path";
+
+// src/framework/loadCatalog.ts
+import { parse } from "yaml";
+
+// src/framework/openapi.ts
+var METHODS = ["get", "put", "post", "delete", "patch", "head", "options", "trace", "query"];
+function hashString(s) {
+  let h = 2166136261;
+  for (let i = 0;i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+function pointerGet(doc, ref) {
+  if (!ref.startsWith("#/"))
+    return;
+  return ref.slice(2).split("/").map((k) => k.replace(/~1/g, "/").replace(/~0/g, "~")).reduce((o, k) => o == null ? undefined : o[k], doc);
+}
+function deref(doc, node, seen = []) {
+  if (Array.isArray(node))
+    return node.map((n) => deref(doc, n, seen));
+  if (!node || typeof node !== "object")
+    return node;
+  const n = node;
+  if (typeof n.$ref === "string") {
+    if (seen.includes(n.$ref) || seen.length > 24)
+      return { $ref: n.$ref };
+    const { $ref, ...rest } = n;
+    const target = deref(doc, pointerGet(doc, $ref), [...seen, $ref]);
+    return Object.keys(rest).length ? { ...target, ...deref(doc, rest, seen) } : target;
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(n))
+    out[k] = deref(doc, v, seen);
+  return out;
+}
+function jsonContent(content) {
+  if (!content)
+    return;
+  const key = Object.keys(content).find((k) => /json/i.test(k)) ?? Object.keys(content)[0];
+  return key ? content[key]?.schema : undefined;
+}
+function intentOf(method, op) {
+  if (typeof op["x-binding-intent"] === "string")
+    return op["x-binding-intent"];
+  if (method === "get" || method === "head" || method === "query")
+    return "read";
+  if (["put", "patch", "delete"].includes(method))
+    return "write";
+  return;
+}
+function catalogFromOpenApi(input, source = {}) {
+  const doc = input;
+  if (!doc || typeof doc !== "object" || !doc.paths)
+    throw new Error("This file is not an OpenAPI document: it has no paths.");
+  const operations = [];
+  const productOf = new Map;
+  for (const g of doc["x-tagGroups"] ?? [])
+    g.tags?.forEach((t) => {
+      if (g.name)
+        productOf.set(t, g.name);
+    });
+  for (const [path, rawItem] of Object.entries(doc.paths)) {
+    const item = deref(doc, rawItem);
+    for (const method of METHODS) {
+      const op = item?.[method];
+      if (!op || !op.operationId)
+        continue;
+      const params = [];
+      for (const p of [...item.parameters ?? [], ...op.parameters ?? []]) {
+        if (!p?.name || !p?.in)
+          continue;
+        const pointer = `/${p.in}/${p.name}`;
+        const at = params.findIndex((x) => x.pointer === pointer);
+        const entry = { pointer, name: p.name, required: !!p.required || p.in === "path", schema: p.schema ?? {}, description: p.description };
+        if (at >= 0)
+          params[at] = entry;
+        else
+          params.push(entry);
+      }
+      for (const m of path.matchAll(/\{([^}]+)\}/g)) {
+        if (!params.some((x) => x.pointer === `/path/${m[1]}`))
+          params.unshift({ pointer: `/path/${m[1]}`, name: m[1], required: true, schema: { type: "string" } });
+      }
+      const bodySchema = jsonContent(op.requestBody?.content);
+      const responses = Object.entries(op.responses ?? {}).map(([status, r]) => ({ status, schema: jsonContent(r?.content) }));
+      const extensions = {};
+      for (const [k, v] of Object.entries(op))
+        if (k.startsWith("x-"))
+          extensions[k] = v;
+      operations.push({
+        id: op.operationId,
+        method: method.toUpperCase(),
+        path,
+        summary: op.summary,
+        description: op.description,
+        tags: op.tags ?? [],
+        product: op.tags?.map((t) => productOf.get(t)).find(Boolean),
+        intent: intentOf(method, op),
+        parameters: params,
+        body: bodySchema ? { required: !!op.requestBody?.required, schema: bodySchema } : undefined,
+        responses,
+        extensions
+      });
+    }
+  }
+  const body = JSON.stringify(operations);
+  return {
+    catalogVersion: 1,
+    source: { title: doc.info?.title ?? "API", version: doc.info?.version ?? "", url: source.url },
+    hash: hashString(body),
+    operations,
+    schemas: {}
+  };
+}
+
+// src/framework/loadCatalog.ts
+class CatalogLoadError extends Error {
+  source;
+  constructor(message, source) {
+    super(message);
+    this.source = source;
+    this.name = "CatalogLoadError";
+  }
+}
+function catalogFromText(text, source) {
+  const body = text.trim();
+  if (!body)
+    throw new CatalogLoadError("Nothing to read: the text is empty.", source);
+  let doc;
+  try {
+    doc = body.startsWith("{") ? JSON.parse(body) : parse(body);
+  } catch {
+    throw new CatalogLoadError("The text is not valid JSON or YAML.", source);
+  }
+  try {
+    return catalogFromOpenApi(doc, source.includes("://") ? { url: source } : {});
+  } catch (e) {
+    throw new CatalogLoadError(e instanceof Error ? e.message : "The text is not an OpenAPI document.", source);
+  }
+}
+
+// src/framework/expr.ts
+var cache = new Map;
+function segments(path) {
+  return path.replace(/\[(\*|\d+)\]/g, ".$1").split(".").filter(Boolean);
+}
+function parse2(expr) {
+  const hit = cache.get(expr);
+  if (hit)
+    return hit;
+  const e = expr.trim();
+  let parsed;
+  if (e.startsWith("$")) {
+    const segs = segments(e);
+    const [h, id] = segs;
+    if (h === "$item")
+      parsed = { head: { type: "item" }, path: segs.slice(1) };
+    else if ((h === "$context" || h === "$steps") && id)
+      parsed = { head: { type: h === "$context" ? "context" : "steps", id }, path: segs.slice(2) };
+    else
+      throw new Error(`Unknown source "${h}" in "${expr}".`);
+  } else {
+    const colon = e.indexOf(":");
+    if (colon < 1)
+      throw new Error(`"${expr}" must read "<componentId>:<slot>".`);
+    const [slot, ...path] = segments(e.slice(colon + 1));
+    if (!slot)
+      throw new Error(`"${expr}" names no slot.`);
+    parsed = { head: { type: "slot", component: e.slice(0, colon), slot }, path };
+  }
+  cache.set(expr, parsed);
+  return parsed;
+}
+
+// src/framework/schema.ts
+var obj = (s) => s && typeof s === "object" ? s : {};
+function flat(s) {
+  const o = obj(s);
+  const parts = [o, ...(o.allOf ?? []).map(flat)];
+  if (parts.length === 1 && !o.oneOf && !o.anyOf)
+    return o;
+  const props = {};
+  const required = [];
+  parts.forEach((p) => {
+    Object.assign(props, p.properties ?? {});
+    required.push(...p.required ?? []);
+  });
+  const alt = (o.oneOf ?? o.anyOf)?.map(flat).find((x) => x.type !== "null");
+  return { ...alt ?? {}, ...o, properties: Object.keys(props).length ? props : alt?.properties, required };
+}
+var views = new WeakMap;
+
+// src/framework/validate.ts
+function validateRegistry(fw) {
+  const kinds = new Set(fw.descriptors.map((d) => d.kind));
+  const issues = [];
+  const ids = new Set(fw.registry.screens.map((s) => s.id));
+  const seen = new Set;
+  const screens = fw.registry.screens.map((S) => {
+    if (!ID.test(S.id)) {
+      issues.push({ severity: "error", screen: S.id, code: "registry.invalid-id", message: `Screen id "${S.id}" must be lowercase kebab-case segments joined by dots.` });
+      return { ...S, components: [] };
+    }
+    const components = S.components.filter((c) => {
+      if (!ID.test(c.bindId)) {
+        issues.push({ severity: "error", screen: S.id, component: c.bindId, code: "registry.invalid-id", message: `Component id "${c.bindId}" must be lowercase kebab-case segments joined by dots.` });
+        return false;
+      }
+      if (!kinds.has(c.kind)) {
+        issues.push({ severity: "error", screen: S.id, component: c.bindId, code: "registry.unknown-kind", message: `"${c.label}" uses ${c.kind}, which has no descriptor.` });
+        return false;
+      }
+      if (seen.has(c.bindId)) {
+        issues.push({ severity: "error", screen: S.id, component: c.bindId, code: "registry.duplicate-id", message: `Component id "${c.bindId}" is used twice.` });
+        return false;
+      }
+      seen.add(c.bindId);
+      return true;
+    }).filter((c) => !c.parent || seen.has(c.parent) || (issues.push({ severity: "error", screen: S.id, component: c.bindId, code: "registry.missing-parent", message: `"${c.label}" names a parent that is not on the screen.` }), false));
+    const parent = S.parent && ids.has(S.parent) ? S.parent : undefined;
+    return { ...S, components, parent };
+  });
+  return { registry: { ...fw.registry, screens }, issues };
+}
+
+// src/codegen/helpers.ts
+var HELPERS = `import { useMutation, useQuery } from "@tanstack/react-query";
+
+/** Data for a slot. \`bound\` is false when no API feeds it; keep the UI's own value then. */
+export interface Data<T> { bound: boolean; data: T | undefined; loading: boolean; error: unknown }
+/** An action. \`run\` rejects when a call fails; it resolves at once when no API is connected. */
+export interface Action { bound: boolean; run: (payload?: any) => Promise<void>; running: boolean; error: unknown }
+/** A per-item value, such as a cell in a row. */
+export interface Cell<T> { bound: boolean; read: (item: any) => T | undefined }
+
+export const UNBOUND_DATA: Data<never> = { bound: false, data: undefined, loading: false, error: undefined };
+export const UNBOUND_ACTION: Action = { bound: false, run: async () => {}, running: false, error: undefined };
+export const UNBOUND_CELL: Cell<never> = { bound: false, read: () => undefined };
+
+export class ApiError extends Error {
+  constructor(readonly status: number, readonly data: unknown) { super(\`API call failed (\${status})\`); this.name = "ApiError"; }
+}
+
+/** Reads a path; "*" maps the rest of the path over a list. */
+export function at(value: unknown, path: readonly string[]): any {
+  let v: any = value;
+  for (let i = 0; i < path.length; i++) {
+    if (v == null) return undefined;
+    if (path[i] === "*") return Array.isArray(v) ? v.map(x => at(x, path.slice(i + 1))) : undefined;
+    v = v[path[i]];
+  }
+  return v;
+}
+
+/** The body of a client response; throws on a non-2xx status. Passes through clients that return the body. */
+export function ok(res: any): any {
+  if (res && typeof res === "object" && typeof res.status === "number" && "data" in res && "headers" in res) {
+    if (res.status < 200 || res.status >= 300) throw new ApiError(res.status, res.data);
+    return res.data;
+  }
+  return res;
+}
+
+/** True when every required input has a value. */
+export const has = (inputs: Record<string, unknown>) => Object.values(inputs).every(v => v !== undefined);
+
+/** Throws when a required input has no value. */
+export function need(operation: string, inputs: Record<string, unknown>) {
+  const missing = Object.keys(inputs).filter(k => inputs[k] === undefined);
+  if (missing.length) throw new Error(\`\${operation}: missing \${missing.join(", ")}\`);
+}
+
+/** Drops undefined values. */
+export const defined = (o: Record<string, unknown>): any => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+
+export const path = (v: unknown): any => (v === undefined ? undefined : encodeURIComponent(String(v)));
+
+/** A body from a base value and [keys, value] entries; undefined values are skipped. */
+export function assemble(base: unknown, entries: Array<[string[], unknown]>): any {
+  const out: any = base && typeof base === "object" ? { ...base } : {};
+  for (const [keys, value] of entries) {
+    if (value === undefined) continue;
+    let node = out;
+    keys.slice(0, -1).forEach(k => { node = node[k] = node[k] && typeof node[k] === "object" ? { ...node[k] } : {}; });
+    node[keys[keys.length - 1]] = value;
+  }
+  return out;
+}
+
+/** Adds mapped fields to each item, keeping the fields the API returned. */
+export function mapItems(data: any, map: (item: any) => Record<string, unknown>): any {
+  const one = (item: any) => ({ ...(item && typeof item === "object" ? item : {}), ...map(item) });
+  return Array.isArray(data) ? data.map(one) : data == null ? data : one(data);
+}
+
+export const list = (v: unknown): unknown[] => (Array.isArray(v) ? v : v === undefined ? [] : [v]);
+
+export function finish(failed: unknown[]) {
+  if (failed.length === 1) throw failed[0];
+  if (failed.length) throw new AggregateError(failed, \`\${failed.length} API calls failed\`);
+}
+
+export function useData<T>(key: readonly unknown[], fetch: () => Promise<unknown>, select: (data: any) => T, options: { enabled: boolean; everySeconds?: number }): Data<T> {
+  const q = useQuery({ queryKey: key, queryFn: fetch, select, enabled: options.enabled, refetchInterval: options.everySeconds ? options.everySeconds * 1000 : false });
+  return { bound: true, data: q.data, loading: q.isLoading, error: q.error ?? undefined };
+}
+
+export function useAction(run: (payload?: any) => Promise<void>): Action {
+  const m = useMutation({ mutationFn: run });
+  return { bound: true, run: payload => m.mutateAsync(payload), running: m.isPending, error: m.error ?? undefined };
+}
+`;
+
+// src/codegen/generate.ts
+var GENERATED_MARK = "@generated";
+var HEADER = `// ${GENERATED_MARK} Do not edit: change the bindings and regenerate.
+`;
+var words = (s) => s.split(/[.\-_]+/).filter(Boolean);
+var pascal = (s) => words(s).map((w) => w[0].toUpperCase() + w.slice(1)).join("");
+var camel = (s) => {
+  const p = pascal(s);
+  return p[0].toLowerCase() + p.slice(1);
+};
+var str = (v) => JSON.stringify(v);
+var IDENT = /^[A-Za-z_$][\w$]*$/;
+var prop = (k) => IDENT.test(k) ? k : str(k);
+var orvalName = (id) => IDENT.test(id) ? id[0].toLowerCase() + id.slice(1) : camel(id);
+function tsType(schema, many = false, depth = 0) {
+  const one = () => {
+    if (!schema || typeof schema !== "object" || depth > 3)
+      return "any";
+    const s = schema;
+    if (Array.isArray(s.enum) && s.enum.length && s.enum.every((v) => typeof v === "string"))
+      return s.enum.map(str).join(" | ");
+    switch (s.type) {
+      case "string":
+        return "string";
+      case "integer":
+      case "number":
+        return "number";
+      case "boolean":
+        return "boolean";
+      case "array":
+        return `Array<${tsType(s.items, false, depth + 1)}>`;
+      case "object": {
+        const props = Object.entries(s.properties ?? {});
+        if (!props.length)
+          return "Record<string, any>";
+        return `{ ${props.map(([k, v]) => `${prop(k)}?: ${tsType(v, false, depth + 1)}`).join("; ")}; [key: string]: any }`;
+      }
+      default:
+        return "any";
+    }
+  };
+  return many ? `Array<${one()}>` : one();
+}
+function compileExpr(expr, cx, scope, at) {
+  let p;
+  try {
+    p = parse2(expr);
+  } catch (e) {
+    cx.issue("expr.invalid", e.message, at);
+    return "undefined";
+  }
+  const path = p.path.map(str);
+  const h = p.head;
+  const read = (root, keys) => {
+    cx.use.add("at");
+    return `at(${root}, [${keys.join(", ")}])`;
+  };
+  if (h.type === "item") {
+    if (!scope.item) {
+      cx.issue("expr.no-item", `"${expr}" reads $item, which this slot does not have.`, at);
+      return "undefined";
+    }
+    return path.length ? read("item", path) : "item";
+  }
+  if (h.type === "context") {
+    if (!cx.screen.context.some((c) => c.id === h.id)) {
+      cx.issue("expr.unknown-context", `"${expr}": ${cx.screen.id} declares no context "${h.id}".`, at);
+      return "undefined";
+    }
+    return read("state.context", [str(h.id), ...path]);
+  }
+  if (h.type === "steps") {
+    if (!scope.steps?.has(h.id)) {
+      cx.issue("expr.unknown-step", `"${expr}" reads step "${h.id}", which does not run before it.`, at);
+      return "undefined";
+    }
+    return read("steps", [str(h.id), ...path]);
+  }
+  if (!cx.produces.get(h.component)?.has(h.slot)) {
+    cx.issue("expr.unknown-slot", `"${expr}" reads a value that is not produced on ${cx.screen.id}.`, at);
+    return "undefined";
+  }
+  return read("state", [str(cx.keys.get(h.component)), str(h.slot), ...path]);
+}
+var decode = (k) => k.replace(/~1/g, "/").replace(/~0/g, "~");
+function compileCall(op, request, cx, scope, at) {
+  const e = (x) => compileExpr(x, cx, scope, at);
+  const known = new Set(op.parameters.map((p) => p.pointer));
+  const body = [];
+  let whole;
+  const query = [];
+  const headers = [];
+  for (const [pointer, x] of Object.entries(request)) {
+    const [, where, ...rest] = pointer.split("/");
+    const keys = rest.map(decode);
+    if (where === "body") {
+      if (!op.body) {
+        cx.issue("request.no-body", `${op.id} takes no body, but "${pointer}" is set.`, at);
+        continue;
+      }
+      if (!keys.length)
+        whole = e(x);
+      else
+        body.push(`[[${keys.map(str).join(", ")}], ${e(x)}]`);
+    } else if (!known.has(pointer))
+      cx.issue("request.unknown-input", `${op.id} has no input "${pointer}".`, at);
+    else if (where === "query")
+      query.push(`${prop(keys[0])}: ${e(x)}`);
+    else if (where === "header")
+      headers.push(`${str(keys[0])}: ${e(x)}`);
+  }
+  const args = [...op.path.matchAll(/\{([^}]+)\}/g)].map((m) => {
+    const x = request[`/path/${m[1]}`];
+    if (x === undefined) {
+      cx.issue("request.missing-path", `${op.id} needs "${m[1]}" in its path; it is not connected.`, at);
+      return "undefined";
+    }
+    cx.use.add("path");
+    return `path(${e(x)})`;
+  });
+  if (op.body) {
+    const set = new Set(Object.keys(request).filter((k) => k.startsWith("/body/")).map((k) => decode(k.split("/")[2])));
+    const schema = flat(op.body.schema);
+    const unset = whole ? [] : (schema.required ?? []).filter((f) => !set.has(f));
+    const empty = unset.filter((f) => {
+      const p = flat(schema.properties?.[f]);
+      return p.type === "object" && !p.required?.length;
+    });
+    const gaps = unset.filter((f) => !empty.includes(f));
+    if (gaps.length)
+      cx.warn("request.required-body", `${op.id} requires ${gaps.join(", ")} in its body; not connected.`, at);
+    cx.use.add("assemble");
+    const base = whole ?? (empty.length ? `{ ${empty.map((f) => `${prop(f)}: {}`).join(", ")} }` : "undefined");
+    args.push(`assemble(${base}, [${body.join(", ")}])`);
+  }
+  if (op.parameters.some((p) => p.pointer.startsWith("/query/"))) {
+    cx.use.add("defined");
+    args.push(`defined({ ${query.join(", ")} })`);
+  }
+  const key = `[${[str(op.id), ...args].join(", ")}]`;
+  if (headers.length) {
+    cx.use.add("defined");
+    args.push(`{ headers: defined({ ${headers.join(", ")} }) }`);
+  }
+  const required = op.parameters.filter((p) => p.required).map((p) => `${prop(p.name)}: ${request[p.pointer] === undefined ? "undefined" : e(request[p.pointer])}`);
+  return { fn: orvalName(op.id), call: `${orvalName(op.id)}(${args.join(", ")})`, key, required: required.length ? `{ ${required.join(", ")} }` : "" };
+}
+var selectPath = (selector) => segments(selector.replace(/^\$\.?/, "").replace(/\[\*\]$/, ""));
+function compileSteps(steps, cx, at, ops, imports) {
+  const done = new Set;
+  const blocks = [];
+  let usesPayload = false;
+  cx.use.add("ok");
+  cx.use.add("finish");
+  for (const st of steps) {
+    const op = ops.get(st.operation);
+    if (!op) {
+      cx.issue("catalog.operation-missing", `${st.operation} is not in the API docs.`, at);
+      continue;
+    }
+    const scope = { item: true, steps: done };
+    const call = compileCall(op, st.request, cx, scope, at);
+    imports.add(call.fn);
+    const each = st.forEach ? compileExpr(st.forEach, cx, scope, at) : undefined;
+    if (each)
+      cx.use.add("list");
+    else
+      usesPayload = true;
+    if (call.required)
+      cx.use.add("need");
+    const readsItem = /\bitem\b/.test(call.call + call.required);
+    blocks.push([
+      `    {`,
+      `      const responses: unknown[] = [];`,
+      `      for (const item of ${each ? `list(${each})` : "[payload]"}) {`,
+      readsItem ? "" : `        void item;`,
+      `        try {`,
+      call.required ? `          need(${str(op.id)}, ${call.required});` : "",
+      `          responses.push(ok(await ${call.call}));`,
+      `        } catch (error) {`,
+      st.onError === "stop" ? `          throw error;` : `          failed.push(error);`,
+      `        }`,
+      `      }`,
+      `      steps[${str(st.id)}] = { response: ${each ? "responses" : "responses[0]"} };`,
+      `    }`
+    ].filter(Boolean).join(`
+`));
+    done.add(st.id);
+  }
+  return [
+    `async (${usesPayload ? "payload" : "_payload"}?: any) => {`,
+    `    const steps: Record<string, unknown> = {};`,
+    `    const failed: unknown[] = [];`,
+    ...blocks,
+    `    finish(failed);`,
+    `  }`
+  ].join(`
+`);
+}
+function generate(file, catalog) {
+  const issues = [];
+  const { fw, index, issues: fileIssues } = fromFile(file, catalog);
+  const valid = validateRegistry(fw);
+  issues.push(...fileIssues, ...valid.issues);
+  const ops = new Map(catalog.operations.map((o) => [o.id, o]));
+  const DESC = new Map(fw.descriptors.map((d) => [d.kind, d]));
+  const client = file.output?.client;
+  if (!client)
+    issues.push({ severity: "error", screen: "", code: "output.missing", message: `Set "output": { "dir", "client" } in the bindings file.` });
+  const files = [{ path: "screen-helpers.ts", content: HEADER + HELPERS }];
+  const exports = [];
+  for (const screen of valid.registry.screens) {
+    const name = pascal(screen.id);
+    const keys = new Map;
+    const taken = new Map;
+    for (const c of screen.components) {
+      const k = camel(c.bindId.slice(screen.id.length + 1));
+      if (taken.has(k))
+        issues.push({ severity: "error", screen: screen.id, component: c.bindId, code: "codegen.name-clash", message: `"${c.bindId}" and "${taken.get(k)}" both become "${k}".` });
+      taken.set(k, c.bindId);
+      keys.set(c.bindId, k);
+    }
+    const cx = {
+      screen,
+      keys,
+      use: new Set,
+      produces: new Map(screen.components.map((c) => [c.bindId, new Set(DESC.get(c.kind).slots.filter((s) => s.role === "produce").map((s) => s.id))])),
+      issue: (code, message, at) => issues.push({ severity: "error", screen: screen.id, code, message, ...at }),
+      warn: (code, message, at) => issues.push({ severity: "warning", screen: screen.id, code, message, ...at })
+    };
+    const bindings = new Map;
+    for (const b of index[screen.id] ?? []) {
+      if (!keys.has(b.component)) {
+        cx.issue("binding.unknown-component", `A binding names "${b.component}", which is not registered.`, b);
+        continue;
+      }
+      if (b.state !== "confirmed") {
+        issues.push({ severity: "warning", screen: screen.id, component: b.component, slot: b.slot, code: "binding.draft", message: `${b.component} · ${b.slot} is a draft; it is not generated.` });
+        continue;
+      }
+      bindings.set(`${b.component}|${b.slot}`, b);
+    }
+    const imports = new Set;
+    const types = new Set;
+    const body = [];
+    const ret = [];
+    const apiType = [];
+    const stateType = [];
+    for (const c of screen.components) {
+      const d = DESC.get(c.kind);
+      const k = keys.get(c.bindId);
+      const produce = d.slots.filter((s) => s.role === "produce");
+      if (produce.length)
+        stateType.push(`  ${prop(k)}?: { ${produce.map((s) => `${prop(s.id)}?: ${tsType(s.schema, s.many)}`).join("; ")} };`);
+      const out = [];
+      const outT = [];
+      const unbound = (slot, v) => {
+        cx.use.add(v);
+        out.push(`${prop(slot)}: ${v}`);
+      };
+      for (const s of d.slots.filter((x) => x.role !== "produce")) {
+        const b = bindings.get(`${c.bindId}|${s.id}`);
+        const at = { component: c.bindId, slot: s.id };
+        const v = `${k}${pascal(s.id)}`;
+        if (s.role === "trigger") {
+          types.add("Action");
+          outT.push(`${prop(s.id)}: Action`);
+          if (b?.type !== "steps") {
+            unbound(s.id, "UNBOUND_ACTION");
+            continue;
+          }
+          cx.use.add("useAction");
+          body.push(`  const ${v} = useAction(${compileSteps(b.steps, cx, at, ops, imports)});`);
+          out.push(`${prop(s.id)}: ${v}`);
+          continue;
+        }
+        const T = tsType(s.schema, s.many);
+        if (s.scope) {
+          types.add("Cell");
+          outT.push(`${prop(s.id)}: Cell<${T}>`);
+          if (b?.type !== "expression") {
+            unbound(s.id, "UNBOUND_CELL");
+            continue;
+          }
+          out.push(`${prop(s.id)}: { bound: true, read: (item: any) => ${compileExpr(b.value, cx, { item: true }, at)} }`);
+          continue;
+        }
+        types.add("Data");
+        outT.push(`${prop(s.id)}: Data<${T}>`);
+        if (b?.type === "expression") {
+          out.push(`${prop(s.id)}: { bound: true, data: ${compileExpr(b.value, cx, { item: false }, at)}, loading: false, error: undefined }`);
+          continue;
+        }
+        const op = b?.type === "operation" ? ops.get(b.operation) : undefined;
+        if (b?.type === "operation" && !op)
+          cx.issue("catalog.operation-missing", `${b.operation} is not in the API docs.`, at);
+        if (b?.type !== "operation" || !op) {
+          unbound(s.id, "UNBOUND_DATA");
+          continue;
+        }
+        const call = compileCall(op, b.request, cx, { item: false }, at);
+        imports.add(call.fn);
+        ["useData", "ok"].forEach((h) => cx.use.add(h));
+        if (call.required)
+          cx.use.add("has");
+        const sel = selectPath(b.select).map(str);
+        if (sel.length)
+          cx.use.add("at");
+        const picked = sel.length ? `at(data, [${sel.join(", ")}])` : "data";
+        const map = Object.entries(b.map ?? {});
+        if (map.length)
+          cx.use.add("mapItems");
+        const select = map.length ? `mapItems(${picked}, (item: any) => ({ ${map.map(([f, x]) => `${prop(f)}: ${compileExpr(x, cx, { item: true }, at)}`).join(", ")} }))` : picked;
+        const every = typeof b.load === "object" ? `, everySeconds: ${b.load.everySeconds}` : "";
+        body.push(`  const ${v} = useData<${T}>(${call.key}, async () => ok(await ${call.call}), (data: any) => ${select}, { enabled: ${call.required ? `has(${call.required})` : "true"}${every} });`);
+        out.push(`${prop(s.id)}: ${v}`);
+      }
+      if (out.length) {
+        ret.push(`    ${prop(k)}: { ${out.join(", ")} },`);
+        apiType.push(`  ${prop(k)}: { ${outT.join("; ")} };`);
+      }
+    }
+    if (screen.context.length)
+      stateType.push(`  context?: { ${screen.context.map((c) => `${prop(c.id)}?: ${"schema" in c.shape ? tsType(c.shape.schema, c.many) : c.many ? "Array<any>" : "any"}`).join("; ")} };`);
+    const usesState = [...body, ...ret].some((l) => /\bstate\b/.test(l));
+    const lines = [
+      HEADER.trimEnd(),
+      imports.size ? `import { ${[...imports].sort().join(", ")} } from ${str(client ?? "")};` : null,
+      cx.use.size ? `import { ${[...cx.use].sort().join(", ")} } from "./screen-helpers";` : null,
+      types.size ? `import type { ${[...types].sort().join(", ")} } from "./screen-helpers";` : null,
+      "",
+      `/** ${screen.label}: values its components produce, and what it was opened with. */`,
+      stateType.length ? `export interface ${name}State {
+${stateType.join(`
+`)}
+}` : `export type ${name}State = Record<string, never>;`,
+      "",
+      `export interface ${name}Api {
+${apiType.join(`
+`)}
+}`,
+      "",
+      `/** API data and actions for ${screen.label} (${screen.id}). */`,
+      `export function use${name}Api(${usesState ? "state" : "_state"}: ${name}State = {}): ${name}Api {`,
+      ...body,
+      `  return {`,
+      ...ret,
+      `  };`,
+      `}`,
+      ""
+    ].filter((l) => l !== null);
+    files.push({ path: `${screen.id}.ts`, content: lines.join(`
+`) });
+    exports.push(`export * from "./${screen.id}";`);
+  }
+  files.push({ path: "index.ts", content: HEADER + exports.join(`
+`) + `
+` });
+  return { files, issues };
+}
+
+// src/cli/scan.ts
+import { promises as fs2 } from "node:fs";
+import path2 from "node:path";
+var LITERAL = /componentId\s*(?:=\s*\{?\s*|:\s*)(["'`])([a-z0-9.-]+)\1/g;
+var SKIP = new Set(["node_modules", "dist", "build", ".git", ".next", ".output"]);
+async function* sources(dir) {
+  for (const e of await fs2.readdir(dir, { withFileTypes: true })) {
+    if (SKIP.has(e.name))
+      continue;
+    const p = path2.join(dir, e.name);
+    if (e.isDirectory())
+      yield* sources(p);
+    else if (/\.(tsx?|jsx?)$/.test(e.name))
+      yield p;
+  }
+}
+async function scanIds(dir, file) {
+  const found = new Map;
+  for await (const p of sources(dir))
+    for (const m of (await fs2.readFile(p, "utf8")).matchAll(LITERAL))
+      if (!found.has(m[2]))
+        found.set(m[2], path2.relative(dir, p));
+  const registered = new Set(file.components.map((c) => c.id));
+  const issues = [];
+  for (const [id, where] of found)
+    if (!registered.has(id))
+      issues.push({ severity: "warning", screen: "", component: id, code: "scan.unregistered", message: `In ${where}, but not registered.` });
+  for (const id of registered)
+    if (!found.has(id))
+      issues.push({ severity: "warning", screen: "", component: id, code: "scan.not-found", message: "Registered, but no componentId literal in the source (fine if the id is built from config)." });
+  return issues;
+}
+
+// src/codegen/write.ts
+async function writeScreens(filePath, opts = {}) {
+  const base = path3.dirname(filePath);
+  const file = await readBindings(filePath);
+  const catalog = catalogFromText(await readDocs(file.openapi, base), file.openapi);
+  const { files, issues } = generate(file, catalog);
+  if (opts.src)
+    issues.push(...await scanIds(path3.resolve(opts.src), file));
+  const out = path3.resolve(base, file.output?.dir ?? ".");
+  const result = { issues, out, screens: files.length - 2, changed: [], stale: [] };
+  if (issues.some((i) => i.severity === "error"))
+    return result;
+  await fs3.mkdir(out, { recursive: true });
+  const wanted = new Map(files.map((f) => [path3.join(out, f.path), f.content]));
+  for (const [p, content] of wanted)
+    if (await fs3.readFile(p, "utf8").catch(() => null) !== content)
+      result.changed.push(p);
+  for (const n of await fs3.readdir(out)) {
+    const p = path3.join(out, n);
+    if (n.endsWith(".ts") && !wanted.has(p) && (await fs3.readFile(p, "utf8")).startsWith(`// ${GENERATED_MARK}`))
+      result.stale.push(p);
+  }
+  if (opts.check)
+    return result;
+  for (const p of result.changed)
+    await writeFileAtomic(p, wanted.get(p));
+  for (const p of result.stale)
+    await fs3.unlink(p);
+  return result;
+}
+var describeIssue = (i) => `${i.severity === "error" ? "error  " : "warning"} ${[i.component ?? i.screen, i.slot].filter(Boolean).join(" · ")}: ${i.message}`;
+
 // src/vite/plugin.ts
 function injectOverlay(res, tag) {
   let done = false;
@@ -166,23 +1041,77 @@ function injectOverlay(res, tag) {
   res.write = (chunk, ...rest) => write(patch(chunk), ...rest);
   res.end = (chunk, ...rest) => chunk == null || typeof chunk === "function" ? end(chunk, ...rest) : end(patch(chunk), ...rest);
 }
+async function regenerate(file, log = console.log) {
+  try {
+    const r = await writeScreens(file);
+    for (const i of r.issues)
+      if (i.severity === "error")
+        log(`[api-binding] ${describeIssue(i)}`);
+    if (r.issues.some((i) => i.severity === "error"))
+      log("[api-binding] Screen hooks not regenerated: fix the errors above.");
+    else if (r.changed.length || r.stale.length)
+      log(`[api-binding] Screen hooks regenerated: ${r.changed.length} written, ${r.stale.length} removed.`);
+  } catch (e) {
+    log(`[api-binding] Screen hooks not regenerated: ${e.message}`);
+  }
+}
+async function generateClient(root, log = console.log) {
+  const config = path4.join(root, "orval.config.ts");
+  if (!existsSync(config))
+    return;
+  try {
+    const orval = "orval";
+    const { generate } = await import(orval);
+    await generate(config, root);
+    log("[api-binding] API client generated.");
+  } catch (e) {
+    log(`[api-binding] API client not generated: ${e.message}`);
+  }
+}
 function bindingStudio(options = {}) {
   const base = (options.base ?? "/__binding").replace(/\/+$/, "");
   const tag = `<script type="module" src="${base}/overlay.js"></script>`;
-  let file = "";
+  let file = "", root = "";
+  const norm = (s) => process.platform === "win32" ? path4.resolve(s).toLowerCase() : path4.resolve(s);
+  const isBindingsFile = (p) => {
+    const abs = norm(p), f = norm(file);
+    return !!file && (abs === f || abs.startsWith(f + ".") && abs.endsWith(".tmp"));
+  };
+  const isRegistryFile = (p) => {
+    try {
+      const registry = JSON.parse(readFileSync(file, "utf8")).registry;
+      return typeof registry === "string" && norm(p) === norm(path4.resolve(path4.dirname(file), registry));
+    } catch {
+      return false;
+    }
+  };
   return {
     name: "api-binding-studio",
     apply: "serve",
     configResolved(config) {
-      file = path2.resolve(config.root, options.file ?? "bindings.json");
+      root = config.root;
+      file = path4.resolve(root, options.file ?? "bindings.json");
     },
     transformIndexHtml: (html) => html.includes(tag) ? html : html.replace(/<\/body>/i, `${tag}</body>`),
-    configureServer(server) {
+    config: () => ({ server: { watch: { ignored: [(p) => isBindingsFile(p)] } } }),
+    async configureServer(server) {
+      if (existsSync(file)) {
+        await generateClient(root);
+        await regenerate(file);
+      }
       const allowed = (req) => {
         const origin = req.headers.origin;
         return req.method === "GET" || !origin || new URL(origin).host === req.headers.host;
       };
-      const handle = createStudioHandler({ file, prefix: base, allowed });
+      let queue = Promise.resolve();
+      const onSave = () => {
+        queue = queue.then(() => regenerate(file));
+      };
+      const handle = createStudioHandler({ file, prefix: base, allowed, onSave });
+      server.watcher?.on("change", (p) => {
+        if (p.endsWith(".json") && isRegistryFile(p))
+          onSave();
+      });
       server.middlewares.use((req, res, next) => {
         handle(req, res).then((handled) => {
           if (handled)
@@ -197,5 +1126,7 @@ function bindingStudio(options = {}) {
 }
 export {
   bindingStudio,
-  injectOverlay
+  generateClient,
+  injectOverlay,
+  regenerate
 };