typebulb 0.17.0 → 0.17.2

package/README.md

@@ -260,7 +260,7 @@ Run a bulb **once** and let hot reload drive the loop.
 - **Self-testing a local bulb** — To confirm a bulb works, run it, instrument with `tb.server.log(...)` (prints to the server's stdout, captured in the log — and works **even on a Restricted bulb**), and read it back with `typebulb logs`. That's the loop to verify behaviour without asking the user to copy-paste console output. `tb.fs.write(...)` is handy for dumping large outputs.
 - **Testing a `server.ts` export directly** — `typebulb call <file> <fn> [arg…]` boots `server.ts`, invokes one export, and prints its return as JSON to stdout (logs/errors to stderr, so `… | jq` works). Args after `<fn>` are JSON-or-string; `--args '<json-array>'` (or `--args -` for stdin) escapes tricky quoting. Needs `--trust`.
 - **Mount to the container your `index.html` declares.** The corpus convention is `<div id="root"></div>` with `createRoot(document.getElementById("root")!)`.
-- **All imports at the top of `code.tsx`.** Bare imports (`react`, `d3`, `three`, …) auto-resolve from a CDN — no install step. Declare them in `config.json` `dependencies` anyway: that's what lets `npx typebulb check` fetch type defs (without it you get errors like `TS2875: react/jsx-runtime`) and pins versions.
+- **All imports at the top of `code.tsx`, and every bare import declared in `config.json` `dependencies`.** Bare imports (`react`, `d3`, `three`, …) resolve from a CDN — no install step — but declaring them is **required, not optional**: an import missing from `dependencies` is a lint error that fails `npx typebulb check` *and* refuses to run. Declaring is also what pins versions and lets `check` fetch type defs (without it you get errors like `TS2875: react/jsx-runtime`). So a bulb with imports must carry a `config.json` with a matching `dependencies` entry for each.
 - **Theme-aware styling.** Style off CSS variables / `currentColor` so the bulb reads correctly in both light and dark; the host sets the theme.
 - **`tb.ai()` takes more than the basics** — the full shape is `tb.ai({ messages, system?, reasoning?, provider?, model?, webSearch? })` → `Promise<{ text }>`. `webSearch` defaults **on** in the CLI (you supply your own key); pass `webSearch: false` to turn it off. For token-by-token output use `tb.ai.stream(...)` (see [`tb.ai()` § Streaming](#streaming)).
 - **`tb.theme` drives the `html[data-theme]` attribute** — style off that selector (`html[data-theme="dark"] { … }`); don't read `tb.theme` to branch your rendering.
@@ -342,6 +342,7 @@ Add API keys to your `.env` file:
 | `gemini` | `GOOGLE_API_KEY` |
 | `openrouter` | `OPENROUTER_API_KEY` |
 | `ollama` | *(none — local server)* |
+| `openai-compat` | `TB_AI_API_KEY` *(optional)* + `TB_AI_BASE_URL` |
 
 Optionally, set your default provider and model:
 
@@ -391,9 +392,11 @@ for await (const c of tb.ai.stream({ messages })) {
 
 Breaking the loop stops the stream; same options as `tb.ai()`. **`kind: "reasoning"` chunks require `reasoning: 1-3` and a thinking-capable model**.
 
-### Local Models
+### Ollama & OpenAI-compatible endpoints
 
-`provider: "ollama"` talks to a local [Ollama](https://ollama.com) server over its OpenAI-compatible endpoint — no API key, defaults to `http://localhost:11434` (override with `OLLAMA_HOST`). CLI-only (typebulb.com can't reach your localhost). `typebulb models` lists your installed Ollama models alongside cloud ones.
+`provider: "ollama"` is the zero-config local preset: it talks to a local [Ollama](https://ollama.com) server over its OpenAI-compatible endpoint — no API key, defaults to `http://localhost:11434` (override with `OLLAMA_HOST`). `typebulb models` lists your installed Ollama models alongside cloud ones.
+
+`provider: "openai-compat"` is the generic escape hatch to *any* OpenAI-compatible endpoint — local or remote (LM Studio, vLLM, a self-hosted box, a keyed proxy, a cloud OpenAI-compat vendor). Set `TB_AI_BASE_URL` (the OpenAI-style base URL ending in `/v1`, e.g. `http://localhost:1234/v1` — `/chat/completions` is appended) and an optional `TB_AI_API_KEY`. Set `TB_AI_MODEL` explicitly (no auto-discovery).
 
 ### Proxying Claude