typebulb 0.4.0 → 0.4.1

package/README.md

@@ -1,13 +1,36 @@
 # typebulb
 
-Run single-file TypeScript apps. A `.bulb.md` file bundles code, HTML, CSS, and server-side logic in one markdown file — `typebulb` compiles and serves it locally with hot reload.
+Run single-file apps from markdown. A `.bulb.md` file bundles code, styles, data, and config in one file. `typebulb` compiles and serves it locally with hot reload.
 
-Create bulbs on [typebulb.com](https://typebulb.com) and export, or generate `.bulb.md` files with any AI coding tool.
+Create bulbs on [typebulb.com](https://typebulb.com) and export, or generate `.bulb.md` files with any AI coding tool. See the [FAQ](https://typebulb.com/faq) for the bulb format and `tb.*` API reference.
 
 ## Quick Start
 
+A bulb is a markdown file with named code blocks:
+
+````markdown
+---
+format: typebulb/v1
+name: My App
+---
+
+**code.tsx**
+
+```tsx
+document.getElementById("root")!.textContent = "Hello from a bulb!";
+```
+
+**index.html**
+
+```html
+<div id="root"></div>
 ```
-npx typebulb my-bulb.bulb.md
+````
+
+Run it:
+
+```
+npx typebulb my-app.bulb.md
 ```
 
 Or install globally:
@@ -31,34 +54,54 @@ typebulb --version             Show version
 
 ## Features
 
-- **Hot reload** — Recompiles on save and refreshes the browser (on by default; disable with `--no-watch`)
-- **Filesystem access** — `tb.fs.read()` and `tb.fs.write()` for local files
-- **Env files** — `.env` and `.env.local` auto-loaded from cwd
-- **AI calls** — `tb.ai()` for general-purpose AI (chatbots, agents, experiments). Set API keys in `.env` (see below).
 - **Server-side code** — Add a `**server.ts**` section; exported functions become callable from the browser via `tb.server.<name>()` (e.g., `export async function query(...)` → `await tb.server.query(...)`)
 - **CLI logging** — `tb.server.log(...)` prints to the CLI's stdout
+- **Env files** — `.env` and `.env.local` auto-loaded from cwd
 - **Server mode** — `--server` runs only the `**server.ts**` section in Node, skipping the web server. Bulbs with only `**server.ts**` (no `**code.tsx**`) use this mode automatically.
+- **Filesystem access** — `tb.fs.read()` and `tb.fs.write()` for local files
+- **Hot reload** — Recompiles on save and refreshes the browser (on by default; disable with `--no-watch`)
 - **Package resolution** — Client dependencies are automatically resolved by generating import maps (same resolver as typebulb.com). Server dependencies are automatically installed via npm.
+- **AI calls** — `tb.ai()` for general-purpose AI (chatbots, agents, experiments). `tb.models()` lists available models. Set API keys in `.env` (see below).
 
 ## AI Setup
 
 Bulbs can call AI providers via `tb.ai()`. Add API keys to your `.env` file:
 
-```
-ANTHROPIC_API_KEY=sk-ant-...
-OPENAI_API_KEY=sk-...
-GOOGLE_API_KEY=AIza...
-OPENROUTER_API_KEY=sk-or-...
-```
+| Provider name | API key env var |
+|---------------|-----------------|
+| `anthropic` | `ANTHROPIC_API_KEY` |
+| `openai` | `OPENAI_API_KEY` |
+| `gemini` | `GOOGLE_API_KEY` |
+| `openrouter` | `OPENROUTER_API_KEY` |
 
-Set your provider and model:
+Set your default provider and model:
 
 ```
 TB_AI_PROVIDER=anthropic
 TB_AI_MODEL=claude-haiku-4-5-20251001
 ```
 
-Both provider and model must be specified — either here or per-call via `tb.ai({ provider: "openai", model: "gpt-4o", ... })`.
+Both can be overridden per-call: `tb.ai({ provider: "gemini", model: "gemini-2.5-flash", ... })`.
+
+### Reasoning
+
+`tb.ai()` accepts an optional `reasoning` parameter (0–3) that hints at how much extended thinking the model should use:
+
+| Level | Label | Effect |
+|-------|-------|--------|
+| 0 | Min | No extended reasoning (default) |
+| 1 | Low | Light reasoning |
+| 2 | Med | Moderate reasoning |
+| 3 | Max | Maximum reasoning |
+
+```typescript
+const { text } = await tb.ai({
+  messages: [{ role: "user", content: "Explain quantum tunneling" }],
+  reasoning: 2,
+});
+```
+
+Provider support varies — the level is mapped to provider-specific parameters (e.g. Anthropic's adaptive thinking, OpenAI's reasoning effort).
 
 ## Limitations
 

package/dist/index.js

@@ -231,6 +231,8 @@ AI API:
     TB_AI_PROVIDER=anthropic
     TB_AI_MODEL=claude-haiku-4-5-20251001
   Both can be overridden per-call: tb.ai({ provider: "openai", model: "gpt-4o", ... })
+  Optional reasoning depth (0=min, 1=low, 2=med, 3=max):
+    tb.ai({ ..., reasoning: 2 })
 
 Examples:
   typebulb my-editor.bulb.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typebulb",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Local bulb runner CLI for Typebulb",
   "license": "MIT",
   "engines": { "node": ">=18" },