typebulb 0.11.2 → 0.11.4

package/README.md

@@ -1,12 +1,12 @@
 # typebulb
 
-Run single-file markdown apps that run in many contexts:
+**Typebulb** runs apps in markdown files called **bulbs**. To run bulbs:
 
-1. Localhost in your browser and optionally in `nodejs`, which can talk via a secure bridge.
-2. Embedded in agent messages when viewed with `npx typebulb agent:claude`.
-3. Published on [typebulb.com](https://typebulb.com) or edited in its online IDE. See [FAQ](https://typebulb.com/faq).
+* `npx typebulb`. When you want a quick local app or tool where the overhead of an entire npm project is overkill *(trivial for your LLM to convert to when you actually need to)*. Can be entirely client code, or both client and nodejs code that talk via a secure bridge.
+* `npx typebulb agent:claude`. When you want to view Claude Code conversations with embedded bulbs in the agent messages.
+* **[typebulb.com](https://typebulb.com)**. When you want to share tools, visualizations, experiments etc. See [FAQ](https://typebulb.com/faq).
 
-`typebulb` serves the first two cases, by compiling and serving hot-reloadable bulbs locally.
+The `typebulb` CLI enables the first two cases, by compiling and serving hot-reloadable bulbs locally.
 
 A `.bulb.md` file bundles code, styles, data, and config in one file.
 
@@ -94,8 +94,8 @@ button {
 {
   "description": "A button that increments a counter.",
   "dependencies": {
-    "react": "^19.2.3",
-    "react-dom": "^19.2.3"
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
   }
 }
 ```
@@ -251,12 +251,16 @@ The agent viewer turns that block into a live, sandboxed app, with a *breakout
 
 **Sizing is the viewer's job, not yours.** The agent viewer renders each embed *inline* by default — fit to the conversation column, with height capped so a tall bulb doesn't run away — plus a per-embed toggle to *spread* it to the full transcript width and height. Don't fight the layout from inside the bulb: no need to set a width, reserve height, or guess how much room you'll get.
 
-**One layout rule the bulb must get right: vertical space on the root is `padding`, not `margin`.** The embed auto-sizes by reporting `document.body.scrollHeight`, and a vertical margin on the root element *collapses* (a body's first/last child margin escapes through to the viewport) so it isn't captured in that measurement — the host then sizes the frame a margin short and you get a stray scrollbar. The page-style `margin: 32px auto` common on a standalone wrapper is exactly this trap. Keep the horizontal `auto` for centering, but move the vertical part to padding:
+**Prefer `padding` over `margin` for vertical space on the root.** The viewer measures an embed by `document.body.scrollHeight`, and the runtime makes `body` a block formatting context so a root child's vertical margin (yours, or a UA default like `<h1>`'s) is contained rather than escaping the measurement — so you no longer have to get this exactly right. It's still cleaner to keep the horizontal `auto` for centering and move the vertical space to padding:
 
 ```css
 .wrap { margin: 0 auto; padding: 24px 16px; }   /* not: margin: 24px auto */
 ```
 
+**Fixing a broken embed?** Re-emit it under the *same* `name:` — the viewer folds the old version into a stub and keeps your fix as the live one. (A rename is treated as a new bulb.)
+
+**A broken embed reads back.** Emit it and move on; embeds usually just work. If the user says one broke, the viewer has already forwarded its compile/runtime error to `typebulb logs claude`, name-tagged (`[embed <name>]`) — pull it from there and fix, instead of asking the user to copy-paste.
+
 ## Tips for Agents
 
 - **`config.json` `description`** is the bulb's SEO meta description — keep it to one or two plain sentences (~150–160 chars), or it gets truncated.