@symbiotejs/symbiote 3.8.1 → 3.8.2

package/README.md

@@ -9,12 +9,10 @@
 
 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 custom elements that work everywhere: in any framework, in plain HTML, 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, not to replace it
-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
+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 in v3.x?
 
@@ -28,7 +26,6 @@ Here are the three most important differences between Symbiote.js and other fram
 - **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
 
@@ -66,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
@@ -145,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
@@ -163,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$()`):
@@ -203,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',
@@ -219,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 (`*`)
@@ -251,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', {
@@ -265,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:
 
@@ -298,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
@@ -311,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 {
@@ -329,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
@@ -341,19 +260,13 @@ CSS values are parsed automatically - quoted strings become strings, numbers bec
 - **Framework-agnostic solutions** - one codebase, any context
 - **Modern AI-first web** - expose the application state to WebMCP tools automatically
 
-## Browser support
-
-All modern browsers: Chrome, Firefox, Safari, Edge, Opera.
-
 ## 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/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.