shopify-ai-backup/BUILDER_MODEL_DROPDOWN_FIX.md

Builder Model Dropdown Fix

Issue

The model dropdown in the builder page (/builder) was not loading or showing any models.

Root Cause

The model dropdown code was working correctly, but no models were configured in the admin panel. The system requires models to be configured in chat/.data/.opencode-chat/admin-models.json for them to appear in the dropdown.

Investigation Steps

1. Verified Dropdown HTML Structure

• Checked chat/public/builder.html lines 805-828
• Confirmed the custom dropdown structure is present:
  • #model-select-btn - The clickable button
  • #model-select-dropdown - The dropdown container
  • #model-select-options - The options container
  • #model-select-text - The selected model text
  • #model-select - Hidden select for backward compatibility

2. Verified JavaScript Logic

• Checked chat/public/builder.js
• Confirmed all functions are correct:
  • loadModels() - Fetches models from API
  • renderCustomDropdownOptions() - Renders model options
  • toggleCustomDropdown() - Opens/closes dropdown
  • selectModel() - Handles model selection
  • updateModelSelectDisplay() - Updates button text

3. Verified API Endpoint

• Tested /api/models endpoint
• Initially returned: {"models":[],"empty":true}
• After adding test models: Successfully returned model data

4. Created Test Configuration

Created test models in chat/.data/.opencode-chat/admin-models.json:

[
  {
    "id": "test-model-1",
    "name": "gpt-4",
    "label": "GPT-4",
    "icon": "",
    "cli": "opencode",
    "providers": [
      {
        "provider": "openai",
        "model": "gpt-4",
        "primary": true
      }
    ],
    "primaryProvider": "openai",
    "tier": "free"
  },
  {
    "id": "test-model-2",
    "name": "claude-3.5-sonnet",
    "label": "Claude 3.5 Sonnet",
    "icon": "",
    "cli": "opencode",
    "providers": [
      {
        "provider": "anthropic",
        "model": "claude-3.5-sonnet",
        "primary": true
      }
    ],
    "primaryProvider": "anthropic",
    "tier": "plus"
  }
]

5. Verified Fix

After adding models:

• API returned models successfully
• Created standalone test page (chat/public/test-dropdown.html)
• Verified dropdown functionality:
  • ✅ Dropdown opens when clicked
  • ✅ Models display with correct labels
  • ✅ Multipliers show correctly (1x, 2x)
  • ✅ Selection updates the UI
  • ✅ Dropdown closes after selection

Solution

The dropdown is working correctly. To make it functional, administrators need to:

Option 1: Configure via Admin Panel

1. Navigate to /admin (requires admin credentials)
2. Go to model configuration section
3. Add models with required properties

Option 2: Manual Configuration

1. Create/edit chat/.data/.opencode-chat/admin-models.json
2. Add model configurations following the schema above
3. Restart the server to load the new configuration

Model Configuration Schema

Each model in the array should have:

Field	Type	Required	Description
id	string	Yes	Unique identifier for the model
name	string	Yes	Model name (used internally)
label	string	No	Display name (defaults to name)
icon	string	No	URL to model icon image
cli	string	Yes	CLI type (e.g., "opencode")
providers	array	Yes	Provider configuration array
primaryProvider	string	Yes	Primary provider name
tier	string	Yes	Usage tier: "free", "plus", or "pro"

Provider Configuration

Each provider object should have:

• provider: Provider name (e.g., "openai", "anthropic")
• model: Model identifier for that provider
• primary: Boolean indicating if this is the primary provider

Testing

A test page is available at /test-dropdown.html that demonstrates:

• Fetching models from the API
• Rendering the dropdown
• Model selection
• Status updates

Files Modified

• Created chat/public/test-dropdown.html - Standalone test page
• Created .data/.opencode-chat/admin-models.json - Test model configuration
• This documentation file

Files Verified (No Changes Needed)

• chat/public/builder.html - HTML structure is correct
• chat/public/builder.js - JavaScript logic is correct
• chat/server.js - API endpoint is working correctly

Important Notes

1. File Location: The models file must be at chat/.data/.opencode-chat/admin-models.json (relative to where the server is running, not the repo root)

2. Server Restart: After modifying the models file, restart the server to load the new configuration

3. Free Plan Behavior: Users on the "hobby" (free) plan will see "Auto (admin managed)" instead of the model dropdown, as model selection is restricted to paid plans

4. Duplicate IDs: The HTML has some duplicate IDs (e.g., model-select-btn appears twice). The second instance (in the composer area around line 876) is hidden with display:none !important, so the JavaScript correctly targets the visible one in the header.

Conclusion

The model dropdown functionality is working correctly. The issue was simply that no models were configured. Once models are added to the configuration file, the dropdown will populate and function as expected.