@symbiotejs/symbiote 3.8.1 → 3.8.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/llms-full.txt CHANGED
@@ -2,32 +2,36 @@
2
2
 
3
3
  <img src="https://rnd-pro.com/svg/symbiote/index.svg" width="200" alt="Symbiote.js">
4
4
 
5
- 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.
5
+ Symbiote.js is a lightweight, standards-first UI library built on Web Components. It extends Custom Elements with reactive data bindings, portable HTML templates, app-wide state, routing, and SSR. It works directly with browser APIs and updates bound DOM properties without virtual DOM reconciliation or excess repainting. The library has zero runtime dependencies and needs neither a compiler nor a build step. A bundler remains optional, though it is recommended for production performance.
6
6
 
7
- 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.
7
+ ## Why Symbiote.js?
8
8
 
9
- Here are the three most important differences between Symbiote.js and other frameworks:
10
- 1. Natural DOM Extension Philosophy - designed to extend platform, not to replace it
11
- 2. Runtime-Agnostic HTML Templates - outstanding flexibility for rendering strategies and further customization
12
- 3. Powerful App-wide State Management - combine data contexts without bloated boilerplate or external tools
9
+ **Runtime Agnostic Templates (RAT)** are the main reason. A Symbiote.js template is an HTML string that describes markup and named bindings. It is independent of a component instance, render function, runtime, and templating tool. You can define, customize, compose, render, and reuse it at any point in the application lifecycle, on the client or the server.
10
+
11
+ RAT keeps UI structure, data bindings, and actions declarative across client rendering, SSR, SSG, and hybrid rendering. Because the template remains a plain HTML string, a component can work beside other UI frameworks without converting its template to framework-specific syntax.
12
+
13
+ Three design choices define the library:
14
+
15
+ 1. Runtime Agnostic Templates keep representation separate from component logic and make templates portable across runtimes and rendering strategies.
16
+ 2. Direct DOM extension keeps components as real Custom Elements that standard browser APIs can inspect and control.
17
+ 3. App-wide state connects components without prop drilling. Named contexts provide the data sources, while namespace bindings such as `APP/user` give templates and components explicit access to them.
13
18
 
14
19
  ## What's new in v3.x?
15
20
 
16
- - **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).
17
- - **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.
18
- - **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.
19
- - **Computed properties refined** - reactive derived state with microtask batching.
20
- - **Path-based router** - optional `AppRouter` module with `:param` extraction, route guards, and lazy loading.
21
- - **Exit animations** - `animateOut(el)` for CSS-driven exit transitions, integrated into itemize API.
22
- - **Dev mode** - `Symbiote.devMode` enables verbose warnings; import `devMessages.js` for full human-readable messages.
23
- - **DSD hydration** - `ssrMode` supports both light DOM and Declarative Shadow DOM.
24
- - **Class property fallback** - binding keys not in `init$` fall back to own class properties/methods.
25
- - **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.
26
- - And [more](https://github.com/symbiotejs/symbiote.js/blob/webmcp/CHANGELOG.md).
21
+ - WebMCP support exposes live Symbiote UI actions as browser-native tools for agents, with public discovery and invocation APIs for application adapters. See the [WebMCP docs](https://github.com/symbiotejs/symbiote.js/blob/main/docs/webmcp.md).
22
+ - Server-side rendering uses `SSR.processHtml()` for complete HTML or `SSR.renderToStream()` for streamed chunks. On the client, `ssrMode` attaches bindings to existing DOM without rendering it again.
23
+ - The `isoMode` flag lets one component work in SSR and client-only scenarios without environment-specific component logic. It hydrates server-rendered content when present and otherwise renders the template from scratch.
24
+ - Computed properties provide reactive derived state with microtask batching.
25
+ - The optional `AppRouter` module supports path parameters, route guards, and lazy loading.
26
+ - The `animateOut(el)` helper provides CSS-driven exit transitions and integrates with the Itemize API.
27
+ - `Symbiote.devMode` enables verbose warnings. Import `devMessages.js` for full, human-readable messages.
28
+ - `ssrMode` hydrates both Light DOM and Declarative Shadow DOM.
29
+ - Binding keys absent from `init$` fall back to the component's own class properties and methods.
30
+ - The `lazyMode` flag defers component initialization and rendering until it enters the viewport. The `lazy` attribute provides the same behavior for `itemize` containers with large data sets.
27
31
 
28
32
  ## Quick start
29
33
 
30
- No install needed - run this directly in a browser:
34
+ Run this example directly in a browser without installing the package:
31
35
 
32
36
  ```html
33
37
  <script type="module">
@@ -51,7 +55,7 @@ No install needed - run this directly in a browser:
51
55
  <my-counter></my-counter>
52
56
  ```
53
57
 
54
- Or install via npm:
58
+ For npm-based projects:
55
59
 
56
60
  ```bash
57
61
  npm i @symbiotejs/symbiote
@@ -61,58 +65,26 @@ npm i @symbiotejs/symbiote
61
65
  import Symbiote, { html, css } from '@symbiotejs/symbiote';
62
66
  ```
63
67
 
64
- ## Isomorphic Web Components
65
-
66
- 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:
67
- ```js
68
- class MyComponent extends Symbiote {
69
- isoMode = true;
70
- count = 0;
71
- increment() {
72
- this.$.count++;
73
- }
74
- }
75
-
76
- MyComponent.template = html`
77
- <h2 ${{textContent: 'count'}}></h2>
78
- <button ${{onclick: 'increment'}}>Click me!</button>
79
- `;
80
- MyComponent.reg('my-component');
81
- ```
82
-
83
- 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.
68
+ ## Core concepts
84
69
 
85
- ### SSR - one class, zero config
70
+ ### Runtime Agnostic Templates (RAT)
86
71
 
87
- Server rendering doesn't need a virtual DOM, a reconciler, or framework-specific packages:
72
+ A template is a plain HTML string that describes markup and named bindings. It does not run inside a component instance or close over `this`; Symbiote.js resolves the component and data context when the template is rendered or hydrated. Templates can be tested, moved between files, and reused across browser and server environments.
88
73
 
89
74
  ```js
90
- import { SSR } from '@symbiotejs/symbiote/node/SSR.js';
91
-
92
- await SSR.init(); // patches globals with linkedom
93
- await import('./my-app.js'); // components register normally
75
+ // Separate file: my-component.template.js
76
+ import { html } from '@symbiotejs/symbiote';
94
77
 
95
- let html = await SSR.processHtml('<my-app></my-app>');
96
- SSR.destroy();
78
+ export default html`
79
+ <h1>{{title}}</h1>
80
+ <button ${{onclick: 'doSomething'}}>Go</button>
81
+ `;
97
82
  ```
98
83
 
99
- 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).
100
-
101
- ### How it compares
102
-
103
- | | **Symbiote.js** | **Next.js (React)** | **Lit** (`@lit-labs/ssr`) |
104
- |--|----------------|---------------------|----|
105
- | **Isomorphic code** | Same code, `isoMode` auto-detects | Server Components vs Client Components split | Same code, but load-order constraints |
106
- | **Hydration** | Binding-based - attaches to existing DOM, no diffing | `hydrateRoot()` - must produce identical output or errors | Requires `ssr-client` + hydrate support module |
107
- | **Packages** | 1 module + `linkedom` peer dep | Full framework buy-in | 3 packages: `ssr`, `ssr-client`, `ssr-dom-shim` |
108
- | **Streaming** | `renderToStream()` async generator | `renderToPipeableStream()` | Iterable `RenderResult` |
109
- | **Mismatch handling** | Not needed - bindings attach to whatever DOM exists | Hard errors if server/client output differs | N/A |
110
- | **Template output** | Clean HTML with `bind=` attributes | HTML with framework markers | HTML with `<!--lit-part-->` comment markers |
111
- | **Lock-in** | None - standard Web Components | Full framework commitment | Lit-specific, but Web Components |
112
-
113
- **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.
84
+ The `html` function supports two interpolation modes:
114
85
 
115
- ## Core concepts
86
+ - An object creates a reactive binding: `${{onclick: 'handler'}}`
87
+ - A string or number uses native concatenation: `${pageTitle}`
116
88
 
117
89
  ### Reactive state
118
90
 
@@ -130,65 +102,37 @@ TodoItem.template = html`
130
102
  `;
131
103
  ```
132
104
 
133
- State changes update the DOM synchronously. No virtual DOM, no scheduling, no surprises. And since components are real DOM elements, state is accessible from the outside via standard APIs:
105
+ State changes update bound DOM properties synchronously, without a virtual DOM or scheduler. Because components are real DOM elements, their state is also accessible through standard APIs:
134
106
 
135
107
  ```js
136
108
  document.querySelector('my-counter').$.count = 42;
137
109
  ```
138
110
 
139
- This makes it easy to control Symbiote-based widgets and microfrontends from any host application - no framework adapters, just DOM.
140
-
141
- ### Templates
142
-
143
- Templates are plain HTML strings - context-free, easy to test, easy to move between files:
144
-
145
- ```js
146
- // Separate file: my-component.template.js
147
- import { html } from '@symbiotejs/symbiote';
148
-
149
- export default html`
150
- <h1>{{title}}</h1>
151
- <button ${{onclick: 'doSomething'}}>Go</button>
152
- `;
153
- ```
154
-
155
- The `html` function supports two interpolation modes:
156
- - **Object** → reactive binding: `${{onclick: 'handler'}}`
157
- - **String/number** → native concatenation: `${pageTitle}`
111
+ Any host application can control a Symbiote.js widget or microfrontend through the DOM API. It does not need a framework adapter.
158
112
 
159
113
  ### Itemize (dynamic reactive lists)
160
114
 
161
- Render lists from data arrays with efficient updates:
115
+ Render lists from data arrays or objects with efficient updates:
162
116
  ```js
163
117
  class TaskList extends Symbiote {
164
118
  tasks = [
165
119
  { name: 'Buy groceries' },
166
120
  { name: 'Write docs' },
167
121
  ];
168
- init$ = {
169
- // Needs to be defined in init$ for pop-up binding to work
170
- onItemClick: () => {
171
- console.log('clicked!');
172
- },
173
- }
174
122
  }
175
123
 
176
124
  TaskList.template = html`
177
- <div itemize="tasks">
125
+ <ul itemize="tasks">
178
126
  <template>
179
- <div ${{onclick: '^onItemClick'}}>{{name}}</div>
127
+ <li>{{name}}</li>
180
128
  </template>
181
- </div>
129
+ </ul>
182
130
  `;
183
131
  ```
184
132
 
185
- 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$`.
186
-
187
- > **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.
188
-
189
133
  ### Pop-up binding (`^`)
190
134
 
191
- 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$()`):
135
+ In a nested component template, the `^` prefix walks up the DOM tree and finds the nearest ancestor with the requested property in its data context (`init$` or `add$()`):
192
136
 
193
137
  ```html
194
138
  <!-- Text binding to parent property: -->
@@ -198,14 +142,12 @@ The `^` prefix works in any nested component template - it walks up the DOM tree
198
142
  <button ${{onclick: '^parentHandler'}}>Click</button>
199
143
  ```
200
144
 
201
- > **Note:** Class property fallbacks are not checked by the `^` walk - the parent must define the property in `init$`.
145
+ ### Namespace bindings and named contexts
202
146
 
203
- ### Named data contexts
204
-
205
- Share state across components without prop drilling:
147
+ A named context is an app-wide data source. A namespace binding such as `APP/user` gives components and templates explicit access to that source without prop drilling:
206
148
 
207
149
  ```js
208
- import { PubSub } from '@symbiotejs/symbiote';
150
+ import { PubSub, html } from '@symbiotejs/symbiote';
209
151
 
210
152
  PubSub.registerCtx({
211
153
  user: 'Alex',
@@ -214,11 +156,14 @@ PubSub.registerCtx({
214
156
 
215
157
  // Any component can read/write:
216
158
  this.$['APP/user'] = 'New name';
159
+
160
+ // Any template can use property directly:
161
+ let template = html`<h2>{{APP/user}}</h2>`;
217
162
  ```
218
163
 
219
164
  ### Shared context (`*`)
220
165
 
221
- Inspired by native HTML `name` attributes - like how `<input name="group">` groups radio buttons - the `ctx` attribute groups components into a shared data context. Components with the same `ctx` value share `*`-prefixed properties:
166
+ Shared contexts follow the same idea as the native HTML `name` attribute used to group radio buttons. The `ctx` attribute assigns components to a shared data context, and components with the same value can use the same `*`-prefixed properties:
222
167
 
223
168
  ```html
224
169
  <upload-btn ctx="gallery"></upload-btn>
@@ -244,13 +189,12 @@ class StatusBar extends Symbiote {
244
189
  }
245
190
  ```
246
191
 
247
- 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.
248
-
249
- The context name can also be inherited via CSS custom property `--ctx`, enabling layout-driven grouping.
192
+ All three components access the same `*files` state. Setting `ctx="gallery"` in HTML and using `*`-prefixed properties removes the need for a parent coordinator, prop drilling, or global store boilerplate. This allows markup to describe complex relationships between reusable components that do not need direct knowledge of one another.
250
193
 
251
- ### Routing (optional module)
194
+ ### Application routing
252
195
 
253
196
  ```js
197
+ // Import optional module:
254
198
  import { AppRouter } from '@symbiotejs/symbiote/core/AppRouter.js';
255
199
 
256
200
  AppRouter.initRoutingCtx('R', {
@@ -260,27 +204,11 @@ AppRouter.initRoutingCtx('R', {
260
204
  });
261
205
  ```
262
206
 
263
- ### Exit animations
264
-
265
- CSS-driven transitions with zero JS animation code:
266
-
267
- ```css
268
- task-item {
269
- opacity: 1;
270
- transition: opacity 0.3s;
271
-
272
- @starting-style { opacity: 0; } /* enter */
273
- &[leaving] { opacity: 0; } /* exit */
274
- }
275
- ```
276
-
277
- `animateOut(el)` sets `[leaving]`, waits for `transitionend`, then removes. Itemize uses this automatically.
207
+ ### CSS styling
278
208
 
279
- ### Styling
209
+ Shadow DOM is optional in Symbiote.js. Use it when a component needs isolation; otherwise, let the component participate in the page's regular styling.
280
210
 
281
- Shadow DOM is **optional** in Symbiote - use it when you need isolation, skip it when you don't. This gives full flexibility:
282
-
283
- **Light DOM** - style components with regular CSS, no barriers:
211
+ Light DOM components use regular CSS:
284
212
 
285
213
  ```js
286
214
  MyComponent.rootStyles = css`
@@ -293,7 +221,9 @@ MyComponent.rootStyles = css`
293
221
  `;
294
222
  ```
295
223
 
296
- **Shadow DOM** - opt-in isolation when needed:
224
+ Symbiote.js applies this style to the nearest containing shadow root, when one exists, or to the document.
225
+
226
+ Use Shadow DOM for opt-in isolation:
297
227
 
298
228
  ```js
299
229
  class Isolated extends Symbiote {}
@@ -304,11 +234,11 @@ Isolated.shadowStyles = css`
304
234
  `;
305
235
  ```
306
236
 
307
- 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.
237
+ Native CSS features remain available. CSS variables cross shadow boundaries, `::part()` exposes selected internals, and modern nesting, `@layer`, and `@container` work without framework abstractions. Light DOM and Shadow DOM components can coexist in the same application.
308
238
 
309
- ### CSS Data Binding
239
+ ### CSS data
310
240
 
311
- Components can read CSS custom properties as reactive state via `cssInit$`:
241
+ Components can read CSS custom property values to initiate reactive state:
312
242
 
313
243
  ```css
314
244
  my-widget {
@@ -324,31 +254,23 @@ MyWidget.template = html`
324
254
  `;
325
255
  ```
326
256
 
327
- 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.
328
-
329
257
  ## Best for
330
258
 
331
- - **Complex widgets** embedded in any host application
332
- - **Low-code HTML-based solutions** - simple declarative everything
333
- - **Micro frontends** - standard custom elements, no framework coupling
334
- - **Reusable component libraries** - works in React, Vue, Angular, or plain HTML
335
- - **SSR-powered apps** - lightweight server rendering without framework lock-in
336
- - **Framework-agnostic solutions** - one codebase, any context
337
- - **Modern AI-first web** - expose the application state to WebMCP tools automatically
338
-
339
- ## Browser support
259
+ - Complex widgets embedded in any host application
260
+ - Low-code, HTML-based interfaces with declarative bindings for UI, data, and actions
261
+ - Microfrontends built from standard Custom Elements without framework coupling
262
+ - Reusable component libraries for React, Vue, Angular, or plain HTML
263
+ - SSR applications that need lightweight server rendering without framework lock-in
264
+ - Framework-agnostic solutions that reuse one codebase across contexts
265
+ - Agent-facing web applications that expose state and actions through WebMCP
340
266
 
341
- All modern browsers: Chrome, Firefox, Safari, Edge, Opera.
342
-
343
- ## Docs & Examples
267
+ ## Docs and examples
344
268
 
345
269
  - [Documentation](https://github.com/symbiotejs/symbiote.js/blob/main/docs/README.md)
346
- - [Lit vs Symbiote.js](https://github.com/symbiotejs/symbiote.js/blob/main/docs/lit-vs-symbiote.md) - Side-by-side comparison
347
- - [Live Examples](https://rnd-pro.com/symbiote/3x/examples/) - Interactive Code Playground
348
- - [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
349
- - [AI / llms.txt](https://rnd-pro.com/symbiote/llms.txt) — index for AI tools
350
- - [Full docs (single file)](https://rnd-pro.com/symbiote/llms-full.txt) — complete merged reference for AI context
351
- - [Changelog](https://github.com/symbiotejs/symbiote.js/blob/main/CHANGELOG.md)
270
+ - [Live examples](https://rnd-pro.com/symbiote/3x/examples/): interactive code playground
271
+ - [JSDA-Kit](https://github.com/rnd-pro/jsda-kit): companion tooling for the server, SSG, bundling, import maps, and native Symbiote.js SSR integration
272
+ - [AI / llms.txt](https://rnd-pro.com/symbiote/llms.txt): index for AI tools
273
+ - [Full docs (single file)](https://rnd-pro.com/symbiote/llms-full.txt): complete merged reference for AI context
352
274
 
353
275
  ## Related articles
354
276
 
@@ -357,11 +279,11 @@ All modern browsers: Chrome, Firefox, Safari, Edge, Opera.
357
279
  - [Symbiote.js vs Lit](https://dev.to/foxeyes/lit-vs-symbiotejs-22gj)
358
280
  - [JSDA Stack - A Revolutionary Simple Approach to Build Modern Web](https://dev.to/foxeyes/jsda-kit-a-revolutionary-simple-approach-to-build-modern-web-1dip)
359
281
 
360
- **Questions or proposals? Welcome to [Symbiote Discussions](https://github.com/symbiotejs/symbiote.js/discussions)!** ❤️
282
+ Questions and proposals are welcome in [Symbiote Discussions](https://github.com/symbiotejs/symbiote.js/discussions).
361
283
 
362
284
  ---
363
285
 
364
- © [rnd-pro.com](https://rnd-pro.com) - MIT License
286
+ © [rnd-pro.com](https://rnd-pro.com), MIT License
365
287
 
366
288
  ---
367
289
 
@@ -405,7 +327,7 @@ my-item {
405
327
 
406
328
  ## Itemize integration
407
329
 
408
- Both itemize processors use `animateOut` automatically for item removal. Items with CSS `transition` + `[leaving]` styles will animate out before being removed from the DOM:
330
+ Itemize processors use `animateOut` automatically for item removal. Items with CSS `transition` + `[leaving]` styles will animate out before being removed from the DOM:
409
331
  ```css
410
332
  user-card {
411
333
  opacity: 1;
@@ -449,7 +371,7 @@ class MyComponent extends Symbiote {}
449
371
  MyComponent.template = html`<h1>{{@attribute-name}}</h1>`;
450
372
  ```
451
373
 
452
- Then use it as an attribute in markup:
374
+ Then use it as an component's attribute in markup:
453
375
  ```html
454
376
  <my-component attribute-name="attribute value"></my-component>
455
377
  ```
@@ -473,7 +395,7 @@ MyComponent.observedAttributes = [
473
395
 
474
396
  ## `bindAttributes()` static method
475
397
 
476
- Bind attributes to property values directly:
398
+ Reflect attribute values to property values:
477
399
  ```js
478
400
  class MyComponent extends Symbiote {
479
401
 
@@ -754,7 +676,69 @@ Named external contexts (`CTX/prop`) are different: they are registered globally
754
676
 
755
677
  ---
756
678
 
757
- ## 10. Treating `init$` as a plain object
679
+ ## 10. Using `{{prop}}` binding syntax inside tag definitions
680
+
681
+ `{{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.
682
+
683
+ ```html
684
+ <!-- WRONG — {{}} syntax does not work inside tag definitions -->
685
+ <div class="{{APP/theme}}">...</div>
686
+ <img src="{{imageUrl}}">
687
+ <button onclick="{{onAction}}">Go</button>
688
+
689
+ <!-- CORRECT — use ${{}} binding object inside the tag -->
690
+ <div ${{'@class': 'APP/theme'}}>...</div>
691
+ <img ${{'@src': 'imageUrl'}}>
692
+ <button ${{onclick: 'onAction'}}>Go</button>
693
+ <div ${{'style.color': 'colorProp'}}>...</div>
694
+
695
+ <!-- CORRECT — or use the bind attribute string syntax -->
696
+ <div bind="@class: APP/theme">...</div>
697
+ <img bind="@src: imageUrl">
698
+ <button bind="onclick: onAction">Go</button>
699
+
700
+ <!-- CORRECT — {{}} works fine in text node content -->
701
+ <h1>Hello, {{userName}}!</h1>
702
+ <p>Theme: {{APP/theme}}</p>
703
+ ```
704
+
705
+ ---
706
+
707
+ ## 11. Expecting two-way data binding
708
+
709
+ 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.
710
+
711
+ ```js
712
+ // WRONG — expecting the binding to also update state on user input
713
+ MyComponent.template = html`
714
+ <input ${{value: 'query'}}>
715
+ `;
716
+
717
+ // CORRECT — handle the input event and write back to state
718
+ class MyComponent extends Symbiote {
719
+ init$ = { query: '' }
720
+ }
721
+
722
+ MyComponent.template = html`
723
+ <input
724
+ ${{value: 'query', oninput: 'onInput'}}
725
+ >
726
+ `;
727
+ ```
728
+ ```js
729
+ class MyComponent extends Symbiote {
730
+ init$ = {
731
+ query: '',
732
+ onInput: (e) => { this.$.query = e.target.value; },
733
+ }
734
+ }
735
+ ```
736
+
737
+ This is intentional — explicit event handling keeps data flow predictable and avoids the hidden side effects that two-way binding can introduce.
738
+
739
+ ---
740
+
741
+ ## 12. Treating `init$` as a plain object
758
742
 
759
743
  `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.
760
744
 
@@ -780,39 +764,46 @@ class MyComponent extends Symbiote {
780
764
 
781
765
  # Context
782
766
 
783
- 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.
767
+ 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.
784
768
 
785
- 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.
769
+ There are seven context types, each addressed by a token prefix in property keys:
770
+
771
+ | Token | Context Type | Scope |
772
+ |-------|-------------|-------|
773
+ | _(none)_ | [Local](#local-context) | Component instance |
774
+ | `^` | [Pop-up](#pop-up-context) | Nearest ancestor that owns the property |
775
+ | `*` | [Shared](#shared-context) | All components sharing a `ctx` attribute |
776
+ | `name/` | [Named](#named-context) | Any component, anywhere |
777
+ | `--` | [CSS Data](#css-data-context) | Inherited from the CSS cascade |
778
+ | `@` | [Attribute](./attributes.md) | HTML attribute on the element |
779
+ | `+` | [Computed](./properties.md#computed-properties) | Derived, auto-recalculated value |
780
+
781
+ ---
786
782
 
787
783
  ## Local context
788
784
 
789
- Local context properties work the same way as component state in most other libraries:
785
+ 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.
786
+
787
+ Define properties in `init$`:
790
788
  ```js
791
789
  class MyComponent extends Symbiote {
792
-
793
790
  init$ = {
794
791
  myProperty: 'some value',
795
792
  }
796
-
797
793
  }
798
794
  ```
799
795
 
800
- Use the `$` proxy to read and write values:
796
+ Use the `$` proxy to read and write values at runtime:
801
797
  ```js
802
798
  class MyComponent extends Symbiote {
803
-
804
799
  init$ = {
805
800
  myProperty: 'some value',
806
801
  }
807
802
 
808
803
  renderCallback() {
809
- // Read:
810
804
  console.log(this.$.myProperty); // > 'some value'
811
-
812
- // Write:
813
805
  this.$.myProperty = 'new value';
814
806
  }
815
-
816
807
  }
817
808
 
818
809
  MyComponent.template = html`
@@ -820,97 +811,143 @@ MyComponent.template = html`
820
811
  `;
821
812
  ```
822
813
 
814
+ 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:
815
+ ```js
816
+ class MyComponent extends Symbiote {
817
+ count = 0;
818
+ label = 'Hello';
819
+ }
820
+ ```
821
+
822
+ > Use `init$` when you need shared (`*`), computed (`+`), or attribute (`@`) props in the same declaration - those tokens are only recognized inside `init$`.
823
+
824
+ See [Properties →](./properties.md) for the full property API: `add$()`, `sub()`, `set$()`, computed props, and more.
825
+
826
+ ---
827
+
823
828
  ## Named context
824
829
 
825
- 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.
830
+ 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.
826
831
 
827
- Example — using named context as a localization tool:
832
+ Use named context when data must be shared across unrelated parts of the application.
833
+
834
+ **Creating a named context:**
835
+ ```js
836
+ import { PubSub } from '@symbiotejs/symbiote';
837
+
838
+ let appCtx = PubSub.registerCtx({
839
+ theme: 'light',
840
+ user: null,
841
+ }, 'APP');
842
+ ```
843
+
844
+ **Accessing it from a component:**
845
+ ```js
846
+ class MyComponent extends Symbiote {
847
+ init$ = {
848
+ 'APP/theme': 'light', // optional local fallback - used if the named context hasn't published yet
849
+ }
850
+
851
+ renderCallback() {
852
+ console.log(this.$['APP/theme']); // read
853
+ this.$['APP/theme'] = 'dark'; // write - updates the named context for all subscribers
854
+ }
855
+ }
856
+
857
+ MyComponent.template = html`
858
+ <div ${{'@class': 'APP/theme'}}>...</div>
859
+ `;
860
+ ```
861
+
862
+ **Example - localization:**
828
863
  ```js
829
864
  import Symbiote, { html, PubSub } from '@symbiotejs/symbiote';
830
865
 
831
- // Create localization map for English:
832
- let EN = {
866
+ let l10nCtx = PubSub.registerCtx({
833
867
  users: 'Users',
834
868
  comments: 'Comments',
835
869
  likes: 'Likes',
836
- };
837
-
838
- // Create localization context:
839
- let l10nCtx = PubSub.registerCtx(EN, 'L10N');
840
-
841
- // Use localized strings in templates:
842
- class MyComponent extends Symbiote { ... }
870
+ }, 'L10N');
843
871
 
844
872
  MyComponent.template = html`
845
873
  <div>{{L10N/users}} - {{numberOfUsers}}</div>
846
874
  <div>{{L10N/comments}} - {{numberOfComments}}</div>
847
875
  <div>{{L10N/likes}} - {{numberOfLikes}}</div>
848
876
  `;
849
- ```
850
877
 
851
- Use `/` token with the context key to access properties: `L10N/users`.
852
-
853
- Switching language:
854
- ```js
855
- let ES = {
878
+ // Switch language at any time - all subscribed components update instantly:
879
+ l10nCtx.multiPub({
856
880
  users: 'Usuarios',
857
881
  comments: 'Comentarios',
858
882
  likes: 'Gustos',
859
- };
860
-
861
- l10nCtx.multiPub(ES);
883
+ });
862
884
  ```
863
885
 
864
- Read and modify named context properties with the `$` proxy:
886
+ You can also read and modify named context directly from any component using the `$` proxy:
865
887
  ```js
866
888
  class MyComponent extends Symbiote {
867
889
  renderCallback() {
868
- // Read:
869
890
  console.log(this.$['L10N/users']);
870
-
871
- // Modify:
872
891
  this.$['L10N/users'] = 'ユーザー';
873
892
  }
874
893
  }
875
894
  ```
876
895
 
877
- More information about `PubSub` in the [PubSub section](./pubsub.md).
896
+ More information about `PubSub` in the [PubSub →](./pubsub.md) section.
897
+
898
+ ---
878
899
 
879
900
  ## Pop-up context
880
901
 
881
- Pop-up binding helps control component interactions based on their DOM position and hierarchy. It works similarly to the CSS cascade model.
902
+ 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.
903
+
904
+ Use the `^` token to reference a pop-up property - in both text bindings and event handlers:
905
+ ```html
906
+ <!-- Text binding to ancestor property: -->
907
+ <div>{{^parentTitle}}</div>
908
+
909
+ <!-- Handler binding to ancestor method: -->
910
+ <button ${{onclick: '^onButtonClicked'}}>Click me!</button>
911
+ ```
882
912
 
883
- Use the `^` token to reference a higher-level property:
884
913
  ```js
885
- class MyComponent extends Symbiote {}
914
+ class MyButton extends Symbiote {}
886
915
 
887
- MyComponent.template = html`
916
+ MyButton.template = html`
917
+ <span>{{^parentTitle}}</span>
888
918
  <button ${{onclick: '^onButtonClicked'}}>Click me!</button>
889
919
  `;
890
920
  ```
891
- Symbiote walks up the DOM tree until it finds the component with `onButtonClicked` registered in its data context.
921
+
922
+ Symbiote walks up the DOM tree until it finds a component with the requested property registered in its context:
923
+ ```js
924
+ class MyEditor extends Symbiote {
925
+ init$ = {
926
+ onButtonClicked: () => console.log('clicked'),
927
+ editorTitle: 'My Editor',
928
+ }
929
+ }
930
+ ```
892
931
 
893
932
  > [!IMPORTANT]
894
- > 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$`:
933
+ > 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$`:
895
934
  > ```js
896
935
  > class ParentComponent extends Symbiote {
897
936
  > init$ = {
898
- > onButtonClicked: () => { console.log('clicked'); },
937
+ > onButtonClicked: () => console.log('clicked'),
899
938
  > parentTitle: 'Hello',
900
939
  > }
901
940
  > }
902
941
  > ```
903
942
 
904
- This is useful for composition, customization, and responsibility splitting:
943
+ Pop-up context is useful for composition - the same child component adapts to whichever ancestor provides the expected behavior:
905
944
  ```js
906
945
  html`
907
946
  <my-text-editor>
908
947
  <complete-toolbar></complete-toolbar>
909
948
  </my-text-editor>
910
949
  `;
911
- ```
912
- Or:
913
- ```js
950
+ // or:
914
951
  html`
915
952
  <my-text-editor>
916
953
  <simplified-toolbar></simplified-toolbar>
@@ -919,19 +956,21 @@ html`
919
956
  `;
920
957
  ```
921
958
 
922
- > Like in CSS, pop-up properties have no collision guard — use additional prefixes in uncontrolled environments.
959
+ > 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.
960
+
961
+ ---
923
962
 
924
963
  ## Shared context
925
964
 
926
- Shared context works similarly to native HTML radio inputs — set the `name` attribute and different inputs connect into one workflow.
965
+ 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.
927
966
 
928
- In 3.x, an explicit context name is **required** for shared properties. Set it using the `ctx` HTML attribute:
967
+ **Assign a context name via the `ctx` HTML attribute:**
929
968
  ```html
930
969
  <upload-btn ctx="gallery"></upload-btn>
931
970
  <file-list ctx="gallery"></file-list>
932
971
  ```
933
972
 
934
- Or using the `--ctx` CSS custom property:
973
+ **Or via the `--ctx` CSS custom property**, which cascades like any CSS variable:
935
974
  ```css
936
975
  .gallery-section {
937
976
  --ctx: gallery;
@@ -945,49 +984,64 @@ Or using the `--ctx` CSS custom property:
945
984
  ```
946
985
 
947
986
  The CSS approach is useful when:
948
- - You want **layout-driven grouping** — components inherit the context from their visual container rather than repeating the attribute on each one
949
- - You need to **reassign context at different DOM levels** — just like any CSS custom property, `--ctx` cascades and can be overridden in nested selectors
950
- - 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
987
+ - You want **layout-driven grouping** - components inherit context from their visual container rather than repeating the attribute on each one
988
+ - You need to **override context at different DOM levels** - just like any CSS custom property, `--ctx` cascades and can be reassigned in nested selectors
989
+ - You work in a **framework-agnostic setup** - CSS context assignment is independent of the host template engine
951
990
 
952
- Then use the `*` token to define shared properties:
991
+ **Define shared properties with the `*` token:**
953
992
  ```js
954
993
  class UploadBtn extends Symbiote {
955
994
  init$ = { '*files': [] }
956
995
 
957
- onUpload() {
996
+ onUpload(newFile) {
958
997
  this.$['*files'] = [...this.$['*files'], newFile];
959
998
  }
960
999
  }
961
1000
 
962
1001
  class FileList extends Symbiote {
963
- init$ = { '*files': [] } // same shared prop — first-registered value wins
1002
+ init$ = { '*files': [] } // same shared prop - first-registered value wins
964
1003
  }
965
1004
  ```
966
1005
 
967
- Both components access the same `*files` state — no parent component, no prop drilling, no global store.
1006
+ 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.
968
1007
 
969
1008
  ### Context name resolution
970
1009
 
971
- The context name is resolved in this order (first match wins):
1010
+ The `ctx` name is resolved in this order (first match wins):
972
1011
 
973
- 1. `ctx="name"` HTML attribute
974
- 2. `--ctx` CSS custom property (inherited from ancestors)
1012
+ 1. `ctx="name"` HTML attribute on the element
1013
+ 2. `--ctx` CSS custom property inherited from ancestors
975
1014
 
976
- > **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.
1015
+ > **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).
1016
+
1017
+ ---
977
1018
 
978
1019
  ## CSS Data context
979
1020
 
980
- Symbiote components can initiate their properties from CSS custom property values:
981
- ```css
982
- :root {
983
- --header: 'CSS Data';
984
- --text: 'Hello!';
1021
+ 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.
1022
+
1023
+ Use `cssInit$` to explicitly declare CSS-initialized properties with fallback values:
1024
+ ```js
1025
+ class MyWidget extends Symbiote {
1026
+ cssInit$ = {
1027
+ '--columns': 1,
1028
+ '--label': '',
1029
+ }
985
1030
  }
1031
+
1032
+ MyWidget.template = html`
1033
+ <span>{{--label}}</span>
1034
+ `;
986
1035
  ```
987
1036
 
988
- > CSS custom property values should be valid JSON values, parseable with `JSON.parse()`. Use numbers for boolean flags (`0`/`1`).
1037
+ ```css
1038
+ my-widget {
1039
+ --columns: 3;
1040
+ --label: 'Click me';
1041
+ }
1042
+ ```
989
1043
 
990
- Use CSS values in templates directly:
1044
+ You can also use `--` bindings directly in templates without `cssInit$`:
991
1045
  ```js
992
1046
  class TestApp extends Symbiote {}
993
1047
 
@@ -996,10 +1050,79 @@ TestApp.template = html`
996
1050
  <div>{{--text}}</div>
997
1051
  `;
998
1052
  ```
1053
+ ```css
1054
+ :root {
1055
+ --header: 'CSS Data';
1056
+ --text: 'Hello!';
1057
+ }
1058
+ ```
999
1059
 
1000
- > CSS custom properties are used for value initialization only. After that, they act like normal local context properties.
1060
+ > CSS custom property values must be valid JSON - use quoted strings (`'text'`), numbers, and `0`/`1` for booleans.
1061
+
1062
+ > 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.
1063
+
1064
+ Full details - `updateCssData()`, `dropCssDataCache()`, `ResizeObserver` patterns, and SSR caveats - in the [CSS Data →](./css-data.md) section.
1065
+
1066
+ ---
1067
+
1068
+ ## Choosing the right context type
1069
+
1070
+ | Situation | Use |
1071
+ |-----------|-----|
1072
+ | Component-local reactive state | Local - no token |
1073
+ | Behavior or data passed from an ancestor | Pop-up - `^` |
1074
+ | Sibling components sharing a workflow state | Shared - `*` |
1075
+ | App-wide data, accessed from anywhere in the tree | Named - `/` |
1076
+ | Component configured via CSS / design tokens | CSS Data - `--` |
1077
+ | Reacting to HTML attribute values | Attribute - `@` |
1078
+ | Values derived from other properties | Computed - `+` |
1079
+
1080
+ ---
1081
+
1082
+ ## All context types in one component
1083
+
1084
+ A concise example showing local, attribute, named, shared, and pop-up contexts working together:
1085
+
1086
+ ```js
1087
+ import Symbiote, { html } from '@symbiotejs/symbiote';
1088
+
1089
+ class MyApp extends Symbiote {
1090
+ init$ = {
1091
+ localCtxProp: 'LOCAL',
1092
+ '@attr-test': '', // bound to HTML attribute
1093
+ 'APP/namedProp': 'NAMED', // named context
1094
+ '*sharedProp': 'SHARED', // shared context (requires ctx="..." in HTML)
1095
+ }
1096
+
1097
+ onUpdate() {
1098
+ let suffix = ' updated';
1099
+ this.$.localCtxProp += suffix;
1100
+ this.$['APP/namedProp'] += suffix;
1101
+ this.$['*sharedProp'] += suffix;
1102
+ }
1103
+ }
1104
+
1105
+ MyApp.template = html`
1106
+ <div>local: {{localCtxProp}}</div>
1107
+ <div>attribute: {{@attr-test}}</div>
1108
+ <div>named: {{APP/namedProp}}</div>
1109
+ <div>shared: {{*sharedProp}}</div>
1110
+ <button ${{onclick: 'onUpdate'}}>Update</button>
1111
+ <inner-el></inner-el> <!-- reads ^localCtxProp via pop-up -->
1112
+ `;
1113
+
1114
+ MyApp.reg('my-app');
1001
1115
 
1002
- More details in the [CSS Data](./css-data.md) section.
1116
+ class InnerEl extends Symbiote {}
1117
+ InnerEl.template = html`<h2>pop-up: {{^localCtxProp}}</h2>`;
1118
+ InnerEl.reg('inner-el');
1119
+ ```
1120
+
1121
+ ```html
1122
+ <my-app attr-test="HTML value" ctx="my-ctx"></my-app>
1123
+ ```
1124
+
1125
+ ---
1003
1126
 
1004
1127
  ## Property token summary
1005
1128
 
@@ -1010,8 +1133,8 @@ More details in the [CSS Data](./css-data.md) section.
1010
1133
  | `*` | Shared | `*sharedProp` |
1011
1134
  | `/` | Named | `APP/myProp` |
1012
1135
  | `--` | CSS Data | `--my-css-var` |
1013
- | `@` | Attribute | `@my-attribute` |
1014
- | `+` | Computed | `+computedProp` |
1136
+ | `@` | Attribute - see [Attributes →](./attributes.md) | `@my-attribute` |
1137
+ | `+` | Computed - see [Properties →](./properties.md#computed-properties) | `+computedProp` |
1015
1138
 
1016
1139
  ---
1017
1140
 
@@ -5282,6 +5405,25 @@ class UserCard extends Symbiote {
5282
5405
 
5283
5406
  The returned text is appended to each component-owned tool description.
5284
5407
 
5408
+ ## Direct Invocation
5409
+
5410
+ Applications can discover and invoke tools through public APIs without native browser WebMCP support:
5411
+
5412
+ ```js
5413
+ import { getActiveWebMCPTools, executeWebMCPTool } from '@symbiotejs/symbiote/webmcp';
5414
+
5415
+ let tools = getActiveWebMCPTools();
5416
+ let result = await executeWebMCPTool('submit_order_in_webmcp-panel', { note: 'Ready' });
5417
+ ```
5418
+
5419
+ Use a currently registered name from discovery. `executeWebMCPTool(name, input = {})` invokes the same executor used by native WebMCP, preserving its owner and automatic event-binding context. Synchronous handlers return their result directly; asynchronous handlers return a promise. Automatic handler responses include the state snapshot after the handler finishes.
5420
+
5421
+ Thrown errors, rejected promises, and unavailable tools return `{ isError: true, content: [{ type: 'text', text: '...' }] }`. Hidden or removed tools cannot be invoked. Calls already running are not cancelled when a tool is removed. Rediscover tools after interface changes; names identify current registrations, not permanent instances.
5422
+
5423
+ Discovery returns metadata only. `nativeActive` indicates native browser registration; a value of `false` does not prevent direct invocation. Native registration failure also leaves direct invocation available.
5424
+
5425
+ Direct invocation is an application API and does not provide browser-mediated consent or enforce native `exposedTo` restrictions. An external transport adapter is responsible for authentication, authorization, target selection, input-schema validation, and result serialization. Symbiote supplies no MCP server or transport. Native browser registration options remain unchanged.
5426
+
5285
5427
  ## Notes
5286
5428
 
5287
5429
  - This is an experimental release. Names, metadata shape, and browser APIs may change.