@symbiotejs/symbiote 3.8.0 → 3.8.2

package/README.md

@@ -1,31 +1,31 @@
 [![Tests](https://github.com/symbiotejs/symbiote.js/actions/workflows/tests.yml/badge.svg)](https://github.com/symbiotejs/symbiote.js/actions/workflows/tests.yml)
 [![npm version](https://img.shields.io/npm/v/@symbiotejs/symbiote)](https://www.npmjs.com/package/@symbiotejs/symbiote)
 [![npm downloads](https://img.shields.io/npm/dm/@symbiotejs/symbiote)](https://www.npmjs.com/package/@symbiotejs/symbiote)
-![bundle size](https://img.shields.io/badge/brotli-7.3_kb-blue)
-![types](https://img.shields.io/badge/types-JSDoc+d.ts-blue)
 ![license](https://img.shields.io/badge/license-MIT-green)
 
 # Symbiote.js
 
 <img src="https://rnd-pro.com/svg/symbiote/index.svg" width="200" alt="Symbiote.js">
 
-A lightweight, standards-first UI library built on Web Components. No virtual DOM, no compiler, no build step required - works directly in the browser. A bundler is recommended for production performance, but entirely optional. **~7.3kb** brotli / **~8.1kb** gzip.
+A lightweight, standards-first UI library built on Web Components. No virtual DOM, no compiler, no black boxes, no excess repaints. No build step required - works directly in the browser. A bundler is recommended for production performance, but entirely optional.
 
-Symbiote.js gives you the convenience of a modern framework while staying close to the native platform - HTML, CSS, and DOM APIs. Components are real custom elements that work everywhere: in any framework, in plain HTML, or in a micro-frontend architecture. And with **isomorphic mode**, the same component code works on the server and the client - server-rendered pages hydrate automatically, no diffing, no mismatch errors.
+Here are the three most important differences between Symbiote.js and other frameworks:
+1. **Natural DOM Extension Philosophy** - designed to extend platform APIs, not to replace them
+2. **Runtime-Agnostic HTML Templates** - outstanding flexibility for rendering strategies and further customization
+3. **Powerful App-wide State Management** - combine data contexts without bloated boilerplate or external tools
 
-## What's new?
+## What's new in v3.x?
 
-- **Experimental WebMCP support** - expose live Symbiote UI actions as browser-native tools for agents. See the [WebMCP docs](https://github.com/symbiotejs/symbiote.js/blob/webmcp/docs/webmcp.md).
+- **WebMCP support** - expose live Symbiote UI actions as browser-native tools for agents. See the [WebMCP docs](https://github.com/symbiotejs/symbiote.js/blob/webmcp/docs/webmcp.md).
 - **Server-Side Rendering** - render components to HTML with `SSR.processHtml()` or stream chunks with `SSR.renderToStream()`. Client-side hydration via `ssrMode` attaches bindings to existing DOM without re-rendering.
 - **Isomorphic components** - `isoMode` flag makes components work in both SSR and client-only scenarios automatically. If server-rendered content exists, it hydrates; otherwise it renders the template from scratch. One component, zero conditional logic.
-- **Computed properties** - reactive derived state with microtask batching.
+- **Computed properties refined** - reactive derived state with microtask batching.
 - **Path-based router** - optional `AppRouter` module with `:param` extraction, route guards, and lazy loading.
 - **Exit animations** - `animateOut(el)` for CSS-driven exit transitions, integrated into itemize API.
 - **Dev mode** - `Symbiote.devMode` enables verbose warnings; import `devMessages.js` for full human-readable messages.
 - **DSD hydration** - `ssrMode` supports both light DOM and Declarative Shadow DOM.
 - **Class property fallback** - binding keys not in `init$` fall back to own class properties/methods.
 - **Lazy mode** - `lazyMode` flag defers component initialization and rendering based on viewport visibility. Can also be enabled via the `lazy` attribute on `itemize` containers to efficiently handle massive data sets.
-- And [more](https://github.com/symbiotejs/symbiote.js/blob/webmcp/CHANGELOG.md).
 
 ## Quick start
 
@@ -63,57 +63,6 @@ npm i @symbiotejs/symbiote
 import Symbiote, { html, css } from '@symbiotejs/symbiote';
 ```
 
-## Isomorphic Web Components
-
-One component. Server-rendered or client-rendered - automatically. Set `isoMode = true` and the component figures it out: if server-rendered content exists, it hydrates; otherwise it renders from template. No conditional logic, no separate server/client versions:
-```js
-class MyComponent extends Symbiote {
-  isoMode = true;
-  count = 0;
-  increment() {
-    this.$.count++;
-  }
-}
-
-MyComponent.template = html`
-  <h2 ${{textContent: 'count'}}></h2>
-  <button ${{onclick: 'increment'}}>Click me!</button>
-`;
-MyComponent.reg('my-component');
-```
-
-This exact code runs **everywhere** - SSR on the server, hydration on the client, or pure client rendering. No framework split, no `'use client'` directives, no hydration mismatch errors.
-
-### SSR - one class, zero config
-
-Server rendering doesn't need a virtual DOM, a reconciler, or framework-specific packages:
-
-```js
-import { SSR } from '@symbiotejs/symbiote/node/SSR.js';
-
-await SSR.init();              // patches globals with linkedom
-await import('./my-app.js');   // components register normally
-
-let html = await SSR.processHtml('<my-app></my-app>');
-SSR.destroy();
-```
-
-For large pages, stream HTML chunks with `SSR.renderToStream()` for faster TTFB. See [SSR docs](./docs/ssr.md) and [server setup recipes](./docs/ssr-server.md).
-
-### How it compares
-
-| | **Symbiote.js** | **Next.js (React)** | **Lit** (`@lit-labs/ssr`) |
-|--|----------------|---------------------|----|
-| **Isomorphic code** | Same code, `isoMode` auto-detects | Server Components vs Client Components split | Same code, but load-order constraints |
-| **Hydration** | Binding-based - attaches to existing DOM, no diffing | `hydrateRoot()` - must produce identical output or errors | Requires `ssr-client` + hydrate support module |
-| **Packages** | 1 module + `linkedom` peer dep | Full framework buy-in | 3 packages: `ssr`, `ssr-client`, `ssr-dom-shim` |
-| **Streaming** | `renderToStream()` async generator | `renderToPipeableStream()` | Iterable `RenderResult` |
-| **Mismatch handling** | Not needed - bindings attach to whatever DOM exists | Hard errors if server/client output differs | N/A |
-| **Template output** | Clean HTML with `bind=` attributes | HTML with framework markers | HTML with `<!--lit-part-->` comment markers |
-| **Lock-in** | None - standard Web Components | Full framework commitment | Lit-specific, but Web Components |
-
-**Key insight:** There are no hydration mismatches because there's no diffing. The server produces HTML with binding attributes. The client reads those attributes and adds reactivity. That's it.
-
 ## Core concepts
 
 ### Reactive state
@@ -142,7 +91,7 @@ This makes it easy to control Symbiote-based widgets and microfrontends from any
 
 ### Templates
 
-Templates are plain HTML strings - context-free, easy to test, easy to move between files:
+Templates are plain HTML strings - runtime-agnostic, easy to test, easy to move between files:
 
 ```js
 // Separate file: my-component.template.js
@@ -160,34 +109,24 @@ The `html` function supports two interpolation modes:
 
 ### Itemize (dynamic reactive lists)
 
-Render lists from data arrays with efficient updates:
+Render lists from data arrays or objects with efficient updates:
 ```js
 class TaskList extends Symbiote {
   tasks = [
     { name: 'Buy groceries' },
     { name: 'Write docs' },
   ];
-  init$ = {
-    // Needs to be defined in init$ for pop-up binding to work
-    onItemClick: () => {
-      console.log('clicked!');
-    },
-  }
 }
 
 TaskList.template = html`
-  <div itemize="tasks">
+  <ul itemize="tasks">
     <template>
-      <div ${{onclick: '^onItemClick'}}>{{name}}</div>
+      <li>{{name}}</li>
     </template>
-  </div>
+  </ul>
 `;
 ```
 
-Items have their own state scope. Use the **`^` prefix** to reach higher-level component properties and handlers - `'^onItemClick'` binds to the parent's `onItemClick`, not the item's. Properties referenced via `^` must be defined in the parent's `init$`.
-
-> **Performance Tip:** For massive lists, add the `lazy` attribute to the container (`<div itemize="tasks" lazy>`). It defers component initialization until they enter the viewport and cleans them up when they leave, heavily optimizing memory and rendering performance.
-
 ### Pop-up binding (`^`)
 
 The `^` prefix works in any nested component template - it walks up the DOM tree to find the nearest ancestor that has the property registered in its data context (`init$` or `add$()`):
@@ -200,14 +139,11 @@ The `^` prefix works in any nested component template - it walks up the DOM tree
 <button ${{onclick: '^parentHandler'}}>Click</button>
 ```
 
-> **Note:** Class property fallbacks are not checked by the `^` walk - the parent must define the property in `init$`.
-
 ### Named data contexts
 
 Share state across components without prop drilling:
-
 ```js
-import { PubSub } from '@symbiotejs/symbiote';
+import { PubSub, html } from '@symbiotejs/symbiote';
 
 PubSub.registerCtx({
   user: 'Alex',
@@ -216,6 +152,9 @@ PubSub.registerCtx({
 
 // Any component can read/write:
 this.$['APP/user'] = 'New name';
+
+// Any template can use property directly:
+let template = html`<h2>{{APP/user}}</h2>`;
 ```
 
 ### Shared context (`*`)
@@ -248,11 +187,10 @@ class StatusBar extends Symbiote {
 
 All three components access the same `*files` state - no parent component, no prop drilling, no global store boilerplate. Just set `ctx="gallery"` in HTML and use `*`-prefixed properties. This makes it trivial to build complex component relationships purely in markup, with ready-made components that don't need to know about each other.
 
-The context name can also be inherited via CSS custom property `--ctx`, enabling layout-driven grouping.
-
-### Routing (optional module)
+### Application routing
 
 ```js
+// Import optional module:
 import { AppRouter } from '@symbiotejs/symbiote/core/AppRouter.js';
 
 AppRouter.initRoutingCtx('R', {
@@ -262,23 +200,7 @@ AppRouter.initRoutingCtx('R', {
 });
 ```
 
-### Exit animations
-
-CSS-driven transitions with zero JS animation code:
-
-```css
-task-item {
-  opacity: 1;
-  transition: opacity 0.3s;
-
-  @starting-style { opacity: 0; }  /* enter */
-  &[leaving] { opacity: 0; }       /* exit  */
-}
-```
-
-`animateOut(el)` sets `[leaving]`, waits for `transitionend`, then removes. Itemize uses this automatically.
-
-### Styling
+### CSS Styling
 
 Shadow DOM is **optional** in Symbiote - use it when you need isolation, skip it when you don't. This gives full flexibility:
 
@@ -295,6 +217,8 @@ MyComponent.rootStyles = css`
 `;
 ```
 
+This style will be applied to nearest upper shadow root, if exists and to common document if not.
+
 **Shadow DOM** - opt-in isolation when needed:
 
 ```js
@@ -308,9 +232,9 @@ Isolated.shadowStyles = css`
 
 All native CSS features work as expected: CSS variables flow through shadow boundaries, `::part()` exposes internals, modern nesting, `@layer`, `@container` - no framework abstractions in the way. Mix light DOM and shadow DOM components freely in the same app.
 
-### CSS Data Binding
+### CSS Data
 
-Components can read CSS custom properties as reactive state via `cssInit$`:
+Components can read CSS custom property values to initiate reactive state:
 
 ```css
 my-widget {
@@ -326,8 +250,6 @@ MyWidget.template = html`
 `;
 ```
 
-CSS values are parsed automatically - quoted strings become strings, numbers become numbers. Call `this.updateCssData()` to re-read after runtime CSS changes. This enables CSS-driven configuration: theme values, layout parameters, or localized strings - all settable from CSS without touching JS.
-
 ## Best for
 
 - **Complex widgets** embedded in any host application
@@ -336,32 +258,15 @@ CSS values are parsed automatically - quoted strings become strings, numbers bec
 - **Reusable component libraries** - works in React, Vue, Angular, or plain HTML
 - **SSR-powered apps** - lightweight server rendering without framework lock-in
 - **Framework-agnostic solutions** - one codebase, any context
-
-## Bundle size
-
-| Library | Minified | Gzip | Brotli |
-|---------|----------|------|--------|
-| **Symbiote.js** (core) | 23.6 kb | 8.1 kb | **7.3 kb** |
-| **Symbiote.js** (full, with AppRouter + WebMCP export) | 35.6 kb | 12.1 kb | **11.0 kb** |
-| **Symbiote.js** (WebMCP extension) | 31.4 kb | 10.6 kb | **9.6 kb** |
-| **Lit** 3.3 | 15.5 kb | 6.0 kb | **~5.1 kb** |
-| **React 19 + ReactDOM** | ~186 kb | ~59 kb | **~50 kb** |
-
-Symbiote and Lit have similar base sizes, but Symbiote's **7.3 kb** core includes more built-in features: global state management, lists (itemize API), exit animations, computed properties etc. Lit needs additional packages for comparable features. React is **~7× larger** before adding a router, state manager, or SSR framework.
-
-## Browser support
-
-All modern browsers: Chrome, Firefox, Safari, Edge, Opera.
+- **Modern AI-first web** - expose the application state to WebMCP tools automatically
 
 ## Docs & Examples
 
 - [Documentation](https://github.com/symbiotejs/symbiote.js/blob/main/docs/README.md)
-- [Lit vs Symbiote.js](https://github.com/symbiotejs/symbiote.js/blob/main/docs/lit-vs-symbiote.md) - Side-by-side comparison
 - [Live Examples](https://rnd-pro.com/symbiote/3x/examples/) - Interactive Code Playground
 - [JSDA-Kit](https://github.com/rnd-pro/jsda-kit) - All-in-one companion tool: server, SSG, bundling, import maps, and native Symbiote.js SSR integration
 - [AI / llms.txt](https://rnd-pro.com/symbiote/llms.txt) — index for AI tools
 - [Full docs (single file)](https://rnd-pro.com/symbiote/llms-full.txt) — complete merged reference for AI context
-- [Changelog](https://github.com/symbiotejs/symbiote.js/blob/main/CHANGELOG.md)
 
 ## Related articles
 

package/core/webmcp.js

@@ -22,7 +22,7 @@ import { parseProp } from './parseProp.js';
  * @property {string | ((owner?: any) => string)} [description]
  * @property {Object | ((owner?: any) => Object)} [inputSchema]
  * @property {(args?: Object, owner?: any, event?: Event) => any} [execute]
- * @property {() => boolean} [when]
+ * @property {(owner?: any) => boolean} [when]
  * @property {string[]} [deps]
  * @property {string[]} [exposedTo]
  * @property {Object} [annotations]
@@ -53,6 +53,7 @@ let installedClasses = new WeakSet();
 let pendingOwnerSync = new WeakSet();
 /** @type {WeakMap<object, number>} */
 let ownerVersions = new WeakMap();
+let _modelContext;
 
 function isToolDescriptor(val) {
   return !!val?.[DICT.MCP_TOOL_DESCRIPTOR_MARKER];
@@ -244,13 +245,16 @@ function ownerId(owner) {
 }
 
 function getModelContext() {
+  if (_modelContext) return _modelContext;
   let docCtx = /** @type {any} */ (globalThis.document)?.modelContext;
   if (docCtx?.registerTool) {
-    return docCtx;
+    _modelContext = docCtx;
+    return _modelContext;
   }
   let navCtx = /** @type {any} */ (globalThis.navigator)?.modelContext;
   if (navCtx?.registerTool) {
-    return navCtx;
+    _modelContext = navCtx;
+    return _modelContext;
   }
   return null;
 }
@@ -591,13 +595,16 @@ function scheduleOwnerSync(owner) {
 }
 
 export class ToolDescriptor {
+  /** @type {((args?: Object, owner?: any, event?: Event) => any) | undefined} */
+  #fn;
+
   /** @param {ToolDescriptorOptions} options */
   constructor(options = {}) {
     this[DICT.MCP_TOOL_DESCRIPTOR_MARKER] = true;
     this.name = options.name;
     this.description = options.description || 'Symbiote WebMCP tool.';
     this.inputSchema = options.inputSchema || emptySchema();
-    this.fn = options.execute;
+    this.#fn = options.execute;
     this.when = options.when;
     this.deps = options.deps || [];
     this.exposedTo = options.exposedTo;
@@ -611,15 +618,15 @@ export class ToolDescriptor {
    * @returns {any}
    */
   execute(args = {}, owner, event) {
-    if (typeof this.fn !== 'function') {
+    if (typeof this.#fn !== 'function') {
       throw new Error('ToolDescriptor requires an execute function.');
     }
-    return this.fn.call(owner, args || {}, owner, event);
+    return this.#fn.call(owner, args || {}, owner, event);
   }
 }
 
 export const webMCPRegistry = (() => {
-  let existing = PubSub.getCtx(REGISTRY_UID, false);
+  let existing = PubSub.getCtx(REGISTRY_UID);
   let root = existing || PubSub.registerCtx({}, REGISTRY_UID);
   ensureNestedCtx(root, 'tools');
   ensureNestedCtx(root, 'owners');
@@ -662,32 +669,23 @@ export function registerWebMCPTool(owner, key, descriptor) {
         webMCPRegistry.store.tools.add(publicName, resolvedEntry, true);
       }
       return resolvedEntry;
+    }).catch((e) => {
+      setDiagnostic('lastError', e);
+      throw e;
     });
   }
   webMCPRegistry.store.tools.add(publicName, entry, true);
   return entry;
 }
 
-/** @param {any} owner */
-export function syncWebMCPTools(owner) {
-  if (!owner) return;
-  if (isElementOwner(owner) && !owner.isConnected) {
-    unregisterWebMCPTools(owner);
-    return;
-  }
-  let version = bumpOwnerVersion(owner);
-  let id = ownerId(owner);
-  let desired = collectDesiredTools(owner);
-  setupDeps(owner, desired);
-  let owners = webMCPRegistry.store.owners;
-  let ownerEntry = owners.has(id)
-    ? owners.read(id)
-    : {
-      ownerId: id,
-      ownerType: ownerType(owner),
-      ownerName: ownerName(owner),
-      toolsByKey: {},
-    };
+/**
+ * @param {any} owner
+ * @param {string} id
+ * @param {{ownerId: string, ownerType: string, ownerName: string, toolsByKey: Record<string, string>}} ownerEntry
+ * @param {Array<{key: string, baseName: string, descriptor: ToolDescriptor, executor: Function}>} desired
+ * @param {string} componentDescription
+ */
+function applyDesiredTools(owner, id, ownerEntry, desired, componentDescription) {
   let nextKeys = new Set();
   for (let item of desired) {
     nextKeys.add(item.key);
@@ -703,17 +701,9 @@ export function syncWebMCPTools(owner) {
     if (hasToolName(publicName)) {
       unregisterToolName(publicName);
     }
-    let entry = makeEntry(publicName, item.key, item.descriptor, owner, item.executor);
+    let entry = makeEntryWithComponentDescription(publicName, item.key, item.descriptor, owner, item.executor, componentDescription);
     ownerEntry.toolsByKey[item.key] = publicName;
-    if (entry instanceof Promise) {
-      entry.then((resolvedEntry) => {
-        if (isCurrentOwnerVersion(owner, version)) {
-          webMCPRegistry.store.tools.add(publicName, resolvedEntry, true);
-        }
-      });
-    } else {
-      webMCPRegistry.store.tools.add(publicName, entry, true);
-    }
+    webMCPRegistry.store.tools.add(publicName, entry, true);
   }
   for (let key in ownerEntry.toolsByKey) {
     if (!nextKeys.has(key)) {
@@ -723,9 +713,40 @@ export function syncWebMCPTools(owner) {
   }
   if (Object.keys(ownerEntry.toolsByKey).length) {
     updateOwnerEntry(id, ownerEntry);
-  } else if (owners.has(id)) {
-    owners.delete(id);
+  } else if (webMCPRegistry.store.owners.has(id)) {
+    webMCPRegistry.store.owners.delete(id);
+  }
+}
+
+/** @param {any} owner */
+export function syncWebMCPTools(owner) {
+  if (!owner) return;
+  if (isElementOwner(owner) && !owner.isConnected) {
+    unregisterWebMCPTools(owner);
+    return;
+  }
+  let version = bumpOwnerVersion(owner);
+  let id = ownerId(owner);
+  let desired = collectDesiredTools(owner);
+  setupDeps(owner, desired);
+  let owners = webMCPRegistry.store.owners;
+  let ownerEntry = owners.has(id)
+    ? owners.read(id)
+    : {
+      ownerId: id,
+      ownerType: ownerType(owner),
+      ownerName: ownerName(owner),
+      toolsByKey: {},
+    };
+  let componentDescription = readComponentDescription(owner);
+  if (typeof componentDescription !== 'string') {
+    componentDescription.then((resolved) => {
+      if (!isCurrentOwnerVersion(owner, version)) return;
+      applyDesiredTools(owner, id, ownerEntry, desired, resolved);
+    }).catch((e) => setDiagnostic('lastError', e));
+    return;
   }
+  applyDesiredTools(owner, id, ownerEntry, desired, componentDescription);
 }
 
 /** @param {any} owner */

package/docs/README.md

@@ -41,19 +41,13 @@
 - [**TypeScript**](./typescript.md) — JSDoc types, TypeScript usage, and hybrid template checks
 - [**Security**](./security.md) — Trusted Types and CSP compliance
 
-## Migration
-
-- [**2.x → 3.x Migration Guide**](./migration-2x-to-3x.md) — Breaking changes and upgrade path
-
 ## Additional Resources
 
-- [Lit vs Symbiote.js](./lit-vs-symbiote.md) — Side-by-side comparison
 - [Live Examples](https://rnd-pro.com/symbiote/3x/examples/) - Interactive Code Playground
 - [Common Mistakes](./common-mistakes.md) — Patterns that frequently cause bugs
 - [Examples](./examples.md) — 26 complete working examples
 - [llms.txt](https://rnd-pro.com/symbiote/llms.txt) — index for AI tools
 - [llms-full.txt](https://rnd-pro.com/symbiote/llms-full.txt) — complete merged reference for AI context
-- [Changelog](../CHANGELOG.md)
 - [npm](https://www.npmjs.com/package/@symbiotejs/symbiote)
 - [GitHub Discussions](https://github.com/symbiotejs/symbiote.js/discussions)
 

package/docs/animations.md

@@ -38,7 +38,7 @@ my-item {
 
 ## Itemize integration
 
-Both itemize processors use `animateOut` automatically for item removal. Items with CSS `transition` + `[leaving]` styles will animate out before being removed from the DOM:
+Itemize processors use `animateOut` automatically for item removal. Items with CSS `transition` + `[leaving]` styles will animate out before being removed from the DOM:
 ```css
 user-card {
   opacity: 1;

package/docs/attributes.md

@@ -22,7 +22,7 @@ class MyComponent extends Symbiote {}
 MyComponent.template = html`<h1>{{@attribute-name}}</h1>`;
 ```
 
-Then use it as an attribute in markup:
+Then use it as an component's attribute in markup:
 ```html
 <my-component attribute-name="attribute value"></my-component>
 ```
@@ -46,7 +46,7 @@ MyComponent.observedAttributes = [
 
 ## `bindAttributes()` static method
 
-Bind attributes to property values directly:
+Reflect attribute values to property values:
 ```js
 class MyComponent extends Symbiote {
 

package/docs/common-mistakes.md

@@ -243,7 +243,69 @@ Named external contexts (`CTX/prop`) are different: they are registered globally
 
 ---
 
-## 10. Treating `init$` as a plain object
+## 10. Using `{{prop}}` binding syntax inside tag definitions
+
+`{{prop}}` is a **text node** binding — it only works inside element content. Any binding that targets a tag itself — attributes, DOM properties, event handlers, or CSS custom properties — must use `${{}}` or `bind=""` syntax inside the opening tag.
+
+```html
+<!-- WRONG — {{}} syntax does not work inside tag definitions -->
+<div class="{{APP/theme}}">...</div>
+<img src="{{imageUrl}}">
+<button onclick="{{onAction}}">Go</button>
+
+<!-- CORRECT — use ${{}} binding object inside the tag -->
+<div ${{'@class': 'APP/theme'}}>...</div>
+<img ${{'@src': 'imageUrl'}}>
+<button ${{onclick: 'onAction'}}>Go</button>
+<div ${{'style.color': 'colorProp'}}>...</div>
+
+<!-- CORRECT — or use the bind attribute string syntax -->
+<div bind="@class: APP/theme">...</div>
+<img bind="@src: imageUrl">
+<button bind="onclick: onAction">Go</button>
+
+<!-- CORRECT — {{}} works fine in text node content -->
+<h1>Hello, {{userName}}!</h1>
+<p>Theme: {{APP/theme}}</p>
+```
+
+---
+
+## 11. Expecting two-way data binding
+
+Symbiote.js bindings are **one-way by design** — from state to DOM. There is no `v-model`, `[(ngModel)]`, or `bind:value` equivalent. To react to user input, wire the event handler explicitly and write back to state yourself.
+
+```js
+// WRONG — expecting the binding to also update state on user input
+MyComponent.template = html`
+  <input ${{value: 'query'}}>
+`;
+
+// CORRECT — handle the input event and write back to state
+class MyComponent extends Symbiote {
+  init$ = { query: '' }
+}
+
+MyComponent.template = html`
+  <input
+    ${{value: 'query', oninput: 'onInput'}}
+  >
+`;
+```
+```js
+class MyComponent extends Symbiote {
+  init$ = {
+    query: '',
+    onInput: (e) => { this.$.query = e.target.value; },
+  }
+}
+```
+
+This is intentional — explicit event handling keeps data flow predictable and avoids the hidden side effects that two-way binding can introduce.
+
+---
+
+## 12. Treating `init$` as a plain object
 
 `init$` is processed once at connection time to populate the component's reactive context. Mutating it after the fact has no effect. Use `this.$` or `add$()` for runtime changes.