@symbiotejs/symbiote 3.8.1 → 3.8.2

package/llms-full.txt

@@ -4,12 +4,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?
 
@@ -23,7 +21,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
 
@@ -61,57 +58,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
@@ -140,7 +86,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
@@ -158,34 +104,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$()`):
@@ -198,14 +134,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',
@@ -214,6 +147,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 (`*`)
@@ -246,11 +182,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', {
@@ -260,23 +195,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:
 
@@ -293,6 +212,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
@@ -306,9 +227,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 {
@@ -324,8 +245,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,19 +255,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
 
@@ -405,7 +318,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;
@@ -449,7 +362,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>
 ```
@@ -473,7 +386,7 @@ MyComponent.observedAttributes = [
 
 ## `bindAttributes()` static method
 
-Bind attributes to property values directly:
+Reflect attribute values to property values:
 ```js
 class MyComponent extends Symbiote {
 
@@ -754,7 +667,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.
 
@@ -780,39 +755,46 @@ class MyComponent extends Symbiote {
 
 # Context
 
-Usage context is one of the central things in Symbiote.js. Every Symbiote component is able to analyze its environment, read external settings from its actual position in DOM, and provide data to related components. Symbiote.js utilizes the DOM structure as the basic entity for data flow management and interconnection.
+Context is the central concept in Symbiote.js. Rather than passing data through prop chains or maintaining a separate global store, Symbiote uses the DOM structure itself as the data flow graph. Every component can read from and write to multiple data sources - its **context** is the union of all the sources currently accessible to it.
+
+There are seven context types, each addressed by a token prefix in property keys:
 
-Component context is a sum of all accessible data sources. Each source represents its own type of interaction. Let's have a look at them.
+| Token | Context Type | Scope |
+|-------|-------------|-------|
+| _(none)_ | [Local](#local-context) | Component instance |
+| `^` | [Pop-up](#pop-up-context) | Nearest ancestor that owns the property |
+| `*` | [Shared](#shared-context) | All components sharing a `ctx` attribute |
+| `name/` | [Named](#named-context) | Any component, anywhere |
+| `--` | [CSS Data](#css-data-context) | Inherited from the CSS cascade |
+| `@` | [Attribute](./attributes.md) | HTML attribute on the element |
+| `+` | [Computed](./properties.md#computed-properties) | Derived, auto-recalculated value |
+
+---
 
 ## Local context
 
-Local context properties work the same way as component state in most other libraries:
+Local context is the component's own reactive state, scoped to the instance. It works the same way as component state in other frameworks and is invisible to other components.
+
+Define properties in `init$`:
 ```js
 class MyComponent extends Symbiote {
-
   init$ = {
     myProperty: 'some value',
   }
-
 }
 ```
 
-Use the `$` proxy to read and write values:
+Use the `$` proxy to read and write values at runtime:
 ```js
 class MyComponent extends Symbiote {
-
   init$ = {
     myProperty: 'some value',
   }
 
   renderCallback() {
-    // Read:
     console.log(this.$.myProperty); // > 'some value'
-
-    // Write:
     this.$.myProperty = 'new value';
   }
-
 }
 
 MyComponent.template = html`
@@ -820,97 +802,143 @@ MyComponent.template = html`
 `;
 ```
 
+For simple components without shared or computed props, you can also declare properties as plain class fields - Symbiote picks them up automatically via class-field fallback:
+```js
+class MyComponent extends Symbiote {
+  count = 0;
+  label = 'Hello';
+}
+```
+
+> Use `init$` when you need shared (`*`), computed (`+`), or attribute (`@`) props in the same declaration - those tokens are only recognized inside `init$`.
+
+See [Properties →](./properties.md) for the full property API: `add$()`, `sub()`, `set$()`, computed props, and more.
+
+---
+
 ## Named context
 
-Named context is an external abstract data source accessed by its name. It can contain any application data or be used for a dedicated purpose.
+Named context is a global, named data store created independently of any component. Any component can read from or write to it using the `CONTEXT_NAME/property` syntax - regardless of DOM position.
 
-Example — using named context as a localization tool:
+Use named context when data must be shared across unrelated parts of the application.
+
+**Creating a named context:**
+```js
+import { PubSub } from '@symbiotejs/symbiote';
+
+let appCtx = PubSub.registerCtx({
+  theme: 'light',
+  user: null,
+}, 'APP');
+```
+
+**Accessing it from a component:**
+```js
+class MyComponent extends Symbiote {
+  init$ = {
+    'APP/theme': 'light', // optional local fallback - used if the named context hasn't published yet
+  }
+
+  renderCallback() {
+    console.log(this.$['APP/theme']); // read
+    this.$['APP/theme'] = 'dark';     // write - updates the named context for all subscribers
+  }
+}
+
+MyComponent.template = html`
+  <div ${{'@class': 'APP/theme'}}>...</div>
+`;
+```
+
+**Example - localization:**
 ```js
 import Symbiote, { html, PubSub } from '@symbiotejs/symbiote';
 
-// Create localization map for English:
-let EN = {
+let l10nCtx = PubSub.registerCtx({
   users: 'Users',
   comments: 'Comments',
   likes: 'Likes',
-};
-
-// Create localization context:
-let l10nCtx = PubSub.registerCtx(EN, 'L10N');
-
-// Use localized strings in templates:
-class MyComponent extends Symbiote { ... }
+}, 'L10N');
 
 MyComponent.template = html`
   <div>{{L10N/users}} - {{numberOfUsers}}</div>
   <div>{{L10N/comments}} - {{numberOfComments}}</div>
   <div>{{L10N/likes}} - {{numberOfLikes}}</div>
 `;
-```
 
-Use `/` token with the context key to access properties: `L10N/users`.
-
-Switching language:
-```js
-let ES = {
+// Switch language at any time - all subscribed components update instantly:
+l10nCtx.multiPub({
   users: 'Usuarios',
   comments: 'Comentarios',
   likes: 'Gustos',
-};
-
-l10nCtx.multiPub(ES);
+});
 ```
 
-Read and modify named context properties with the `$` proxy:
+You can also read and modify named context directly from any component using the `$` proxy:
 ```js
 class MyComponent extends Symbiote {
   renderCallback() {
-    // Read:
     console.log(this.$['L10N/users']);
-
-    // Modify:
     this.$['L10N/users'] = 'ユーザー';
   }
 }
 ```
 
-More information about `PubSub` in the [PubSub section](./pubsub.md).
+More information about `PubSub` in the [PubSub →](./pubsub.md) section.
+
+---
 
 ## Pop-up context
 
-Pop-up binding helps control component interactions based on their DOM position and hierarchy. It works similarly to the CSS cascade model.
+Pop-up context lets a child component reach a property defined by an ancestor, without the ancestor needing to pass it down explicitly. Symbiote walks up the DOM tree until it finds a component that has the requested property in its data context.
+
+Use the `^` token to reference a pop-up property - in both text bindings and event handlers:
+```html
+<!-- Text binding to ancestor property: -->
+<div>{{^parentTitle}}</div>
+
+<!-- Handler binding to ancestor method: -->
+<button ${{onclick: '^onButtonClicked'}}>Click me!</button>
+```
 
-Use the `^` token to reference a higher-level property:
 ```js
-class MyComponent extends Symbiote {}
+class MyButton extends Symbiote {}
 
-MyComponent.template = html`
+MyButton.template = html`
+  <span>{{^parentTitle}}</span>
   <button ${{onclick: '^onButtonClicked'}}>Click me!</button>
 `;
 ```
-Symbiote walks up the DOM tree until it finds the component with `onButtonClicked` registered in its data context.
+
+Symbiote walks up the DOM tree until it finds a component with the requested property registered in its context:
+```js
+class MyEditor extends Symbiote {
+  init$ = {
+    onButtonClicked: () => console.log('clicked'),
+    editorTitle: 'My Editor',
+  }
+}
+```
 
 > [!IMPORTANT]
-> The `^` lookup only checks the parent's **data context** (properties registered via `init$` or `add$()`). Class property fallbacks are **not** resolved during this walk. Always define `^`-targeted properties in the parent's `init$`:
+> Pop-up lookup only searches the **data context** (properties registered via `init$` or `add$()`). Plain class properties are not resolved this way. Always declare `^`-targeted properties in the parent's `init$`:
 > ```js
 > class ParentComponent extends Symbiote {
 >   init$ = {
->     onButtonClicked: () => { console.log('clicked'); },
+>     onButtonClicked: () => console.log('clicked'),
 >     parentTitle: 'Hello',
 >   }
 > }
 > ```
 
-This is useful for composition, customization, and responsibility splitting:
+Pop-up context is useful for composition - the same child component adapts to whichever ancestor provides the expected behavior:
 ```js
 html`
   <my-text-editor>
     <complete-toolbar></complete-toolbar>
   </my-text-editor>
 `;
-```
-Or:
-```js
+// or:
 html`
   <my-text-editor>
     <simplified-toolbar></simplified-toolbar>
@@ -919,19 +947,21 @@ html`
 `;
 ```
 
-> Like in CSS, pop-up properties have no collision guard — use additional prefixes in uncontrolled environments.
+> Like the CSS cascade, pop-up context has no collision guard. Use additional prefixes (e.g. `myApp_onSave`) in environments you don't fully control.
+
+---
 
 ## Shared context
 
-Shared context works similarly to native HTML radio inputs — set the `name` attribute and different inputs connect into one workflow.
+Shared context is inspired by native HTML `name` attributes - the same way `<input name="group">` connects radio buttons into one workflow, the `ctx` attribute connects Symbiote components into a shared data context. Components with the same `ctx` name access a common reactive store with no intermediary component required.
 
-In 3.x, an explicit context name is **required** for shared properties. Set it using the `ctx` HTML attribute:
+**Assign a context name via the `ctx` HTML attribute:**
 ```html
 <upload-btn ctx="gallery"></upload-btn>
 <file-list ctx="gallery"></file-list>
 ```
 
-Or using the `--ctx` CSS custom property:
+**Or via the `--ctx` CSS custom property**, which cascades like any CSS variable:
 ```css
 .gallery-section {
   --ctx: gallery;
@@ -945,49 +975,64 @@ Or using the `--ctx` CSS custom property:
 ```
 
 The CSS approach is useful when:
-- You want **layout-driven grouping** — components inherit the context from their visual container rather than repeating the attribute on each one
-- You need to **reassign context at different DOM levels** — just like any CSS custom property, `--ctx` cascades and can be overridden in nested selectors
-- You work in a **framework-agnostic setup** — CSS can be managed separately from markup, so context assignment doesn't depend on template engine or host framework
+- You want **layout-driven grouping** - components inherit context from their visual container rather than repeating the attribute on each one
+- You need to **override context at different DOM levels** - just like any CSS custom property, `--ctx` cascades and can be reassigned in nested selectors
+- You work in a **framework-agnostic setup** - CSS context assignment is independent of the host template engine
 
-Then use the `*` token to define shared properties:
+**Define shared properties with the `*` token:**
 ```js
 class UploadBtn extends Symbiote {
   init$ = { '*files': [] }
 
-  onUpload() {
+  onUpload(newFile) {
     this.$['*files'] = [...this.$['*files'], newFile];
   }
 }
 
 class FileList extends Symbiote {
-  init$ = { '*files': [] }  // same shared prop — first-registered value wins
+  init$ = { '*files': [] }  // same shared prop - first-registered value wins
 }
 ```
 
-Both components access the same `*files` state — no parent component, no prop drilling, no global store.
+Both components read and write the same `*files` store. When one updates it, the other reacts automatically - no parent component, no prop drilling, no global store.
 
 ### Context name resolution
 
-The context name is resolved in this order (first match wins):
+The `ctx` name is resolved in this order (first match wins):
+
+1. `ctx="name"` HTML attribute on the element
+2. `--ctx` CSS custom property inherited from ancestors
 
-1. `ctx="name"` HTML attribute
-2. `--ctx` CSS custom property (inherited from ancestors)
+> **IMPORTANT**: In Symbiote 3.x, `*` properties **require** an explicit `ctx` attribute or `--ctx` variable. Without one, no shared context is created, `*` props have no effect, and dev mode will warn (W6).
 
-> **IMPORTANT**: In 3.x, `*` properties **require** an explicit `ctx` attribute or `--ctx` CSS variable. Without one, the shared context is not created, `*` props have no effect, and dev mode will warn about it.
+---
 
 ## CSS Data context
 
-Symbiote components can initiate their properties from CSS custom property values:
-```css
-:root {
-  --header: 'CSS Data';
-  --text: 'Hello!';
+Symbiote components can initialize their properties from CSS custom property values, enabling CSS-driven configuration: theme tokens, layout parameters, or localized strings - all settable from a stylesheet without touching JavaScript.
+
+Use `cssInit$` to explicitly declare CSS-initialized properties with fallback values:
+```js
+class MyWidget extends Symbiote {
+  cssInit$ = {
+    '--columns': 1,
+    '--label': '',
+  }
 }
+
+MyWidget.template = html`
+  <span>{{--label}}</span>
+`;
 ```
 
-> CSS custom property values should be valid JSON values, parseable with `JSON.parse()`. Use numbers for boolean flags (`0`/`1`).
+```css
+my-widget {
+  --columns: 3;
+  --label: 'Click me';
+}
+```
 
-Use CSS values in templates directly:
+You can also use `--` bindings directly in templates without `cssInit$`:
 ```js
 class TestApp extends Symbiote {}
 
@@ -996,10 +1041,79 @@ TestApp.template = html`
   <div>{{--text}}</div>
 `;
 ```
+```css
+:root {
+  --header: 'CSS Data';
+  --text: 'Hello!';
+}
+```
 
-> CSS custom properties are used for value initialization only. After that, they act like normal local context properties.
+> CSS custom property values must be valid JSON - use quoted strings (`'text'`), numbers, and `0`/`1` for booleans.
+
+> CSS properties are used for **initialization only**. After the component mounts, they act as normal local context properties and no longer track CSS changes. Call `this.updateCssData()` to re-read them after runtime CSS updates.
+
+Full details - `updateCssData()`, `dropCssDataCache()`, `ResizeObserver` patterns, and SSR caveats - in the [CSS Data →](./css-data.md) section.
+
+---
+
+## Choosing the right context type
+
+| Situation | Use |
+|-----------|-----|
+| Component-local reactive state | Local - no token |
+| Behavior or data passed from an ancestor | Pop-up - `^` |
+| Sibling components sharing a workflow state | Shared - `*` |
+| App-wide data, accessed from anywhere in the tree | Named - `/` |
+| Component configured via CSS / design tokens | CSS Data - `--` |
+| Reacting to HTML attribute values | Attribute - `@` |
+| Values derived from other properties | Computed - `+` |
+
+---
 
-More details in the [CSS Data](./css-data.md) section.
+## All context types in one component
+
+A concise example showing local, attribute, named, shared, and pop-up contexts working together:
+
+```js
+import Symbiote, { html } from '@symbiotejs/symbiote';
+
+class MyApp extends Symbiote {
+  init$ = {
+    localCtxProp: 'LOCAL',
+    '@attr-test': '',         // bound to HTML attribute
+    'APP/namedProp': 'NAMED', // named context
+    '*sharedProp': 'SHARED',  // shared context (requires ctx="..." in HTML)
+  }
+
+  onUpdate() {
+    let suffix = ' updated';
+    this.$.localCtxProp += suffix;
+    this.$['APP/namedProp'] += suffix;
+    this.$['*sharedProp'] += suffix;
+  }
+}
+
+MyApp.template = html`
+  <div>local: {{localCtxProp}}</div>
+  <div>attribute: {{@attr-test}}</div>
+  <div>named: {{APP/namedProp}}</div>
+  <div>shared: {{*sharedProp}}</div>
+  <button ${{onclick: 'onUpdate'}}>Update</button>
+  <inner-el></inner-el>  <!-- reads ^localCtxProp via pop-up -->
+`;
+
+MyApp.reg('my-app');
+
+class InnerEl extends Symbiote {}
+InnerEl.template = html`<h2>pop-up: {{^localCtxProp}}</h2>`;
+InnerEl.reg('inner-el');
+```
+
+```html
+<my-app attr-test="HTML value" ctx="my-ctx"></my-app>
+```
+
+---
 
 ## Property token summary
 
@@ -1010,8 +1124,8 @@ More details in the [CSS Data](./css-data.md) section.
 | `*` | Shared | `*sharedProp` |
 | `/` | Named | `APP/myProp` |
 | `--` | CSS Data | `--my-css-var` |
-| `@` | Attribute | `@my-attribute` |
-| `+` | Computed | `+computedProp` |
+| `@` | Attribute - see [Attributes →](./attributes.md) | `@my-attribute` |
+| `+` | Computed - see [Properties →](./properties.md#computed-properties) | `+computedProp` |
 
 ---