# Gotchas and limitations A collection of behaviors worth knowing about before they surprise you. ## Alpha status The library is in early alpha (`0.0.1-alpha.x`). APIs may change; pin your version. ## The rendering model means no re-renders Components are executed **once**. If you're used to re-render loops (React-style), remember that all dynamic behavior must go through signals — bindings registered at element creation time. A component that reads a signal value directly into a static prop will capture that value forever: ```tsx const counter = sig(0); // ❌ static — always renders 0 const a =
{counter.get()}
; // ✅ reactive — updates as counter changes const b ={counter}
; ``` ## Garbage-collection based cleanup Most cleanup is driven by the garbage collector rather than by explicit unmounting: - DOM bindings hold their element in a `WeakRef` and detach themselves **on the next dispatch** after the element is collected. Cleanup is lazy, not instant. - Signals used in JSX are kept alive by the element they're bound to, so inline derived signals are safe: `{s.derive(...)}` won't be collected while the element lives. - **Never strongly reference a bound element inside a binding callback** other than through the argument provided to it — it would defeat the weak-reference cleanup. This applies to `bindSignal` callbacks: ```typescript // ❌ holds myElement strongly → listener leaks bindSignal(s, myElement, () => { myElement.classList.add("x"); }); // ✅ use the callback argument bindSignal(s, myElement, (elem) => { elem.classList.add("x"); }); ``` - Listeners attached with `add()` to a **derived signal you don't keep a reference to** can be silently collected. Use `observe()` for such listeners (see [Signals](./signals.md#reading-and-reacting)). ## Fragments cannot hold signal children `<>...>` fragments are real `DocumentFragment`s and cannot have signals bound as direct children — attempting it throws (this is a limitation of the DOM not this library.) Bind signals inside a regular element instead. ## `unsafeHTML` is an XSS surface With `unsafeHTML` set, string children are parsed as HTML with `DOMParser` — the equivalent of `innerHTML`, with **no sanitization anywhere**. Only use it with fully trusted content. ## Batching semantics Inside `sig.startBatch()` / before `sig.commitBatch()`: - reads return the **pre-batch** values, even after dispatching; - listeners fire once at commit, and listeners added mid-batch get their initial call at commit time. If you forget to call `commitBatch()`, nothing is applied. ## Value identity matters in lists `