{
  "openapi": "3.1.0",
  "info": {
    "title": "ViewSpec Hosted Compiler API",
    "summary": "Compile agent-native ViewSpec IntentBundles into portable CompositionIR and provenance.",
    "description": "ViewSpec is an agent-native UI IR and semantic UI compiler API for deterministic cross-platform UI generation.",
    "version": "1.0.0",
    "license": {
      "name": "MIT",
      "url": "https://github.com/nxrobins/viewspec/blob/main/LICENSE"
    }
  },
  "servers": [
    {
      "url": "https://api.viewspec.dev",
      "description": "Canonical hosted compiler"
    }
  ],
  "externalDocs": {
    "description": "ViewSpec playground and demos",
    "url": "https://viewspec.dev/"
  },
  "x-viewspec-agent-artifacts": {
    "systemPrompt": "https://viewspec.dev/agent-system-prompt.txt",
    "intentBundleSchema": "https://viewspec.dev/agent-intent-bundle.schema.json",
    "agentDocs": "https://github.com/nxrobins/viewspec/blob/main/docs/agent-integration.md"
  },
  "paths": {
    "/v1/compile": {
      "post": {
        "operationId": "compileViewSpecIntentBundle",
        "summary": "Compile a ViewSpec intent bundle",
        "description": "Compiles semantic substrate and view_spec JSON into CompositionIR, style values, diagnostics, timing metadata, quota metadata, and provenance-aware UI artifacts.",
        "tags": ["compiler"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IntentBundle"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Compiled UI artifact",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompileResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed intent bundle"
          },
          "401": {
            "description": "Invalid or missing API key for a protected tier"
          },
          "429": {
            "description": "Quota exceeded"
          }
        }
      },
      "options": {
        "operationId": "compileViewSpecCorsPreflight",
        "summary": "CORS preflight for compile endpoint",
        "responses": {
          "200": {
            "description": "CORS headers accepted"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "IntentBundle": {
        "type": "object",
        "required": ["substrate", "view_spec"],
        "properties": {
          "substrate": {
            "$ref": "#/components/schemas/Substrate"
          },
          "view_spec": {
            "$ref": "#/components/schemas/ViewSpec"
          },
          "motif_library": {
            "type": "object",
            "description": "Optional hosted compiler custom motif library.",
            "additionalProperties": true
          },
          "design": {
            "$ref": "#/components/schemas/DesignRequest"
          }
        },
        "additionalProperties": true
      },
      "DesignRequest": {
        "type": "object",
        "required": ["format", "content"],
        "properties": {
          "format": {
            "type": "string",
            "const": "design.md"
          },
          "content": {
            "type": "string",
            "description": "Opaque DESIGN.md content. Parsing, linting, cycle detection, and token mapping are owned by the API."
          },
          "lint": {
            "type": "boolean",
            "default": true
          }
        },
        "additionalProperties": false
      },
      "Substrate": {
        "type": "object",
        "required": ["id", "root_id", "nodes"],
        "properties": {
          "id": { "type": "string" },
          "root_id": { "type": "string" },
          "nodes": {
            "type": "object",
            "description": "Dictionary of substrate nodes keyed by node ID.",
            "additionalProperties": {
              "$ref": "#/components/schemas/SubstrateNode"
            }
          }
        },
        "additionalProperties": true
      },
      "SubstrateNode": {
        "type": "object",
        "required": ["id", "kind", "attrs", "slots", "edges"],
        "properties": {
          "id": { "type": "string" },
          "kind": { "type": "string" },
          "attrs": { "type": "object", "additionalProperties": true },
          "slots": { "type": "object", "additionalProperties": true },
          "edges": { "type": "object", "additionalProperties": true }
        },
        "additionalProperties": true
      },
      "ViewSpec": {
        "type": "object",
        "required": ["id", "substrate_id", "complexity_tier", "root_region", "regions", "bindings", "groups", "motifs"],
        "properties": {
          "id": { "type": "string" },
          "substrate_id": { "type": "string" },
          "complexity_tier": { "type": "integer", "minimum": 1 },
          "root_region": { "type": "string" },
          "regions": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "bindings": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "groups": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "motifs": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "styles": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "actions": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "projections": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "inputs": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "rules": { "type": "array", "items": { "type": "object", "additionalProperties": true } }
        },
        "additionalProperties": true
      },
      "CompileResponse": {
        "type": "object",
        "required": ["ast"],
        "properties": {
          "ast": {
            "type": "object",
            "description": "Compiled CompositionIR bundle and style values.",
            "additionalProperties": true
          },
          "meta": {
            "$ref": "#/components/schemas/CompileResponseMeta"
          },
          "derivations": {
            "type": "array",
            "description": "Hosted compiler derivation token explanations when available.",
            "items": { "type": "object", "additionalProperties": true }
          },
          "quota": {
            "type": "object",
            "description": "Quota information when returned by the hosted API.",
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "CompileResponseMeta": {
        "type": "object",
        "description": "Compiler timing, tier, usage, diagnostic metadata, and optional DESIGN.md validation results.",
        "properties": {
          "design": {
            "$ref": "#/components/schemas/DesignMetadata"
          }
        },
        "additionalProperties": true
      },
      "DesignMetadata": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "lint_summary": {
            "type": "object",
            "required": ["errors", "warnings", "info"],
            "properties": {
              "errors": { "type": "integer", "minimum": 0 },
              "warnings": { "type": "integer", "minimum": 0 },
              "info": { "type": "integer", "minimum": 0 }
            },
            "additionalProperties": false
          },
          "findings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DesignFinding"
            }
          },
          "applied_tokens": {
            "type": "object",
            "additionalProperties": { "type": "string" }
          },
          "inferred_hints": {
            "type": "object",
            "additionalProperties": { "type": "string" }
          },
          "ignored_tokens": {
            "type": "array",
            "items": { "type": "string" }
          },
          "dropped_tokens": {
            "type": "array",
            "description": "Tokens dropped by API cycle detection.",
            "items": { "type": "string" }
          }
        },
        "additionalProperties": true
      },
      "DesignFinding": {
        "type": "object",
        "required": ["severity", "code", "path", "message"],
        "properties": {
          "severity": {
            "type": "string",
            "enum": ["error", "warning", "info"]
          },
          "code": { "type": "string" },
          "path": { "type": "string" },
          "message": { "type": "string" }
        },
        "additionalProperties": false
      }
    }
  }
}