Content
# Solar
A runtime UI framework built for AI-generated code.
When an AI agent builds UI with React or Vue, it guesses. It guesses prop names, types, and valid values. When it gets something wrong, it gets a stack trace. Stack traces are not machine-readable feedback.
Solar gives agents a clear path. Call `registry.manifest()` and you get a JSON schema of every registered component, including what props it takes and what values are valid. Mount a component with wrong props and you get a `ContractError`, a structured object with `expected`, `received`, and `fix` fields. The agent reads `fix` and retries. No human required.
---
## Core principles
- **Explicit contracts over conventions:** props are typed and validated at the component boundary, not inferred
- **Component registry:** models read a machine-readable manifest before generating any composition code
- **Structured errors:** validation failures return parseable JSON an agent can act on directly
- **Declared side effects:** effects declare what they depend on and what they touch; no implicit subscriptions
- **Typed composition:** slot props enforce which component can fill them, with runtime validation
- **Runtime-based:** no compiler required; debuggable in the browser as-is
- **Small surface area:** fewer primitives means fewer ways to generate something wrong
---
## How it works
### Defining a component
Every component declares its shape explicitly. Register it so other components and models can discover it.
```js
import { createElement, defineComponent, registry } from './framework/index.js'
const Button = defineComponent({
name: 'Button',
props: {
label: { type: 'string', required: true },
onClick: { type: 'function', required: true },
variant: { type: 'string', enum: ['primary', 'secondary'], default: 'primary' },
},
render({ label, onClick, variant }) {
return createElement('button', { class: variant, onclick: onClick }, label)
}
})
registry.register(Button)
```
### Structured errors
Pass the wrong type and you get a structured error, not a string. An agent can parse and self-correct without regex.
```js
Button({ label: 42, onClick: () => {} })
// throws ContractError:
{
"error": "ContractError",
"component": "Button",
"prop": "label",
"expected": "string",
"received": "number",
"fix": "Pass a string value for \"label\""
}
```
### Component registry
Before generating composition code, a model reads the full catalog:
```js
registry.manifest()
// →
[
{
"name": "Button",
"props": {
"label": { "type": "string", "required": true },
"onClick": { "type": "function", "required": true },
"variant": { "type": "string", "enum": ["primary", "secondary"], "default": "primary" }
}
},
...
]
```
### Typed slots (component composition)
A parent component declares which component type can fill a slot. Passing anything else throws a `ContractError`.
```js
const Card = defineComponent({
name: 'Card',
props: {
title: { type: 'string', required: true },
action: { type: 'slot', accepts: 'Button', required: true },
},
render({ title, action }) {
return createElement('div', { class: 'card' },
createElement('h3', {}, title),
action,
)
}
})
// valid
Card({ title: 'Hello', action: Button({ label: 'Go', onClick: () => {} }) })
// throws: Card: prop "action": expected slot(Button), got vnode with no _source
Card({ title: 'Hello', action: createElement('button', {}, 'Go') })
```
### Compact h() notation
`h()` parses a dense array format into a vnode tree. It's registry-aware, so component names resolve automatically.
```js
import { h } from './framework/index.js'
// plain DOM nodes
h(['div', { class: 'row' },
['p', {}, 'Hello'],
['button', { class: 'btn' }, 'Click'],
])
// registered component by name, dispatches to Button()
h(['Button', { label: 'Save', onClick: handleSave, variant: 'primary' }])
```
### Hooks and effects
State is `useState`. Side effects use three explicit primitives instead of a general `useEffect`:
- **`useResource`:** async data fetching with automatic AbortController cancellation on key change
- **`useSubscription`:** event listener that attaches and detaches when source/event/handler changes
- **`onMount` / `onUnmount`:** lifecycle callbacks that run once, not on every render
```js
const UserCard = defineComponent({
name: 'UserCard',
props: { userId: { type: 'number', required: true } },
render({ userId }) {
const [width, setWidth] = useState(window.innerWidth)
// cancels the previous fetch automatically when userId changes
const { data, loading, error } = useResource({
key: userId,
fetch: async (signal) => {
const res = await fetch(`/api/user/${userId}`, { signal })
return res.json()
},
})
// attaches once, re-attaches only if source/event/handler changes
useSubscription({ source: window, event: 'resize', handler: () => setWidth(window.innerWidth) })
onMount(() => analytics.track('UserCard mounted'))
onUnmount(() => analytics.track('UserCard unmounted'))
if (loading) return createElement('p', {}, 'Loading...')
return createElement('p', {}, `${data.name} - viewport: ${width}px`)
}
})
```
---
## Architecture
```
framework/
├── core/
│ ├── createElement.js # vnode factory
│ ├── render.js # mount vnode tree to DOM
│ ├── diff.js # reconcile old and new vnode trees
│ ├── hooks.js # useState, useMemo, useResource, useSubscription, onMount, onUnmount
│ └── scheduler.js # batch and defer re-renders
├── contract/
│ ├── defineComponent.js # strict component definition with prop schema
│ ├── ContractError.js # structured error class with toJSON()
│ ├── validate.js # runtime prop validation
│ └── types.js # primitive type definitions + slot type
├── runtime/
│ ├── reconciler.js # component lifecycle and mount/unmount
│ └── events.js # delegated event handling
├── registry.js # component catalog and manifest
├── h.js # compact array notation parser
└── index.js # public API
```
Components live in `components/`, one per file, default export is the `defineComponent` call, self-registered on import. Rules a model can follow without inference.
---
## Live demo
[Open in StackBlitz](https://stackblitz.com/github/Stahlwalker/framework-solar/tree/main/stackblitz) — runs a 3-step agent loop in the browser: discover components via `registry.manifest()`, catch a `ContractError` on a bad mount, self-correct using the `fix` field.
---
## Getting started
```bash
npm create solarbuild@latest my-app
cd my-app
npm run dev
```
**Cursor plugin:** [cursor.directory/plugins/framework-solar](https://cursor.directory/plugins/framework-solar) — adds Solar rules to Cursor so your AI assistant knows the API out of the box.
Or use the CDN directly. No install, no build step:
```html
<!DOCTYPE html>
<html>
<body>
<div id="app"></div>
<script type="module">
import {
defineComponent, mountComponent, registry,
useState, createElement
} from 'https://cdn.jsdelivr.net/npm/solarbuild/framework/index.js'
const Counter = defineComponent({
name: 'Counter',
props: {},
render() {
const [count, setCount] = useState(0)
return createElement('button', { onclick: () => setCount(n => n + 1) }, `Clicked ${count} times`)
}
})
registry.register(Counter)
mountComponent(Counter, {}, document.getElementById('app'))
</script>
</body>
</html>
```
## Running the demo
```bash
npm run dev
```
Open `http://localhost:3456/demo/` (trailing slash required; it's a static server quirk).
The demo covers all framework features: static rendering, diffing, hooks, contract validation, declared effects, batched updates, registry manifest, compact h() notation, and typed slots.
---
## MCP Server
`solarbuild-mcp` is an MCP server that exposes your Solar component registry as callable tools. AI agents can discover components, validate props, and self-correct at runtime — without reading static docs.
```bash
npm install solarbuild-mcp
```
```json
{
"mcpServers": {
"solarbuild": {
"command": "npx",
"args": ["solarbuild-mcp", "--components", "./components"]
}
}
}
```
**Tools:** `manifest` (full registry schema), `component` (single component schema), `validate` (props validation with fix instructions).
→ [MCP Server docs](https://docs.solarbuild.dev/docs/integrations/mcp) · [npm](https://www.npmjs.com/package/solarbuild-mcp)
---
## Docs
Full documentation at [docs.solarbuild.dev](https://docs.solarbuild.dev)
- [Installation](https://docs.solarbuild.dev/docs/installation)
- [Use Cases](https://docs.solarbuild.dev/docs/use-cases)
- [API Reference](https://docs.solarbuild.dev/docs/api/define-component)
---
## What this is not
- Not a meta-framework. No SSR, no routing, no build pipeline.
- Not a React replacement. Narrower scope, different constraints.
- Not optimized for humans writing components by hand, though it works fine for that too.
The thesis: the next wave of frameworks won't be designed for developers. They'll be designed for the models developers use to write code. This is an early attempt at that.
