@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/README.md CHANGED
@@ -7,32 +7,36 @@
7
7
 
8
8
  <img src="https://rnd-pro.com/svg/symbiote/index.svg" width="200" alt="Symbiote.js">
9
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.
10
+ 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.
11
11
 
12
- 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.
12
+ ## Why Symbiote.js?
13
13
 
14
- Here are the three most important differences between Symbiote.js and other frameworks:
15
- 1. Natural DOM Extension Philosophy - designed to extend platform, not to replace it
16
- 2. Runtime-Agnostic HTML Templates - outstanding flexibility for rendering strategies and further customization
17
- 3. Powerful App-wide State Management - combine data contexts without bloated boilerplate or external tools
14
+ **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.
15
+
16
+ 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.
17
+
18
+ Three design choices define the library:
19
+
20
+ 1. Runtime Agnostic Templates keep representation separate from component logic and make templates portable across runtimes and rendering strategies.
21
+ 2. Direct DOM extension keeps components as real Custom Elements that standard browser APIs can inspect and control.
22
+ 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.
18
23
 
19
24
  ## What's new in v3.x?
20
25
 
21
- - **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).
22
- - **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.
23
- - **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.
24
- - **Computed properties refined** - reactive derived state with microtask batching.
25
- - **Path-based router** - optional `AppRouter` module with `:param` extraction, route guards, and lazy loading.
26
- - **Exit animations** - `animateOut(el)` for CSS-driven exit transitions, integrated into itemize API.
27
- - **Dev mode** - `Symbiote.devMode` enables verbose warnings; import `devMessages.js` for full human-readable messages.
28
- - **DSD hydration** - `ssrMode` supports both light DOM and Declarative Shadow DOM.
29
- - **Class property fallback** - binding keys not in `init$` fall back to own class properties/methods.
30
- - **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.
31
- - And [more](https://github.com/symbiotejs/symbiote.js/blob/webmcp/CHANGELOG.md).
26
+ - 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).
27
+ - 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.
28
+ - 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.
29
+ - Computed properties provide reactive derived state with microtask batching.
30
+ - The optional `AppRouter` module supports path parameters, route guards, and lazy loading.
31
+ - The `animateOut(el)` helper provides CSS-driven exit transitions and integrates with the Itemize API.
32
+ - `Symbiote.devMode` enables verbose warnings. Import `devMessages.js` for full, human-readable messages.
33
+ - `ssrMode` hydrates both Light DOM and Declarative Shadow DOM.
34
+ - Binding keys absent from `init$` fall back to the component's own class properties and methods.
35
+ - 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.
32
36
 
33
37
  ## Quick start
34
38
 
35
- No install needed - run this directly in a browser:
39
+ Run this example directly in a browser without installing the package:
36
40
 
37
41
  ```html
38
42
  <script type="module">
@@ -56,7 +60,7 @@ No install needed - run this directly in a browser:
56
60
  <my-counter></my-counter>
57
61
  ```
58
62
 
59
- Or install via npm:
63
+ For npm-based projects:
60
64
 
61
65
  ```bash
62
66
  npm i @symbiotejs/symbiote
@@ -66,58 +70,26 @@ npm i @symbiotejs/symbiote
66
70
  import Symbiote, { html, css } from '@symbiotejs/symbiote';
67
71
  ```
68
72
 
69
- ## Isomorphic Web Components
70
-
71
- 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:
72
- ```js
73
- class MyComponent extends Symbiote {
74
- isoMode = true;
75
- count = 0;
76
- increment() {
77
- this.$.count++;
78
- }
79
- }
80
-
81
- MyComponent.template = html`
82
- <h2 ${{textContent: 'count'}}></h2>
83
- <button ${{onclick: 'increment'}}>Click me!</button>
84
- `;
85
- MyComponent.reg('my-component');
86
- ```
87
-
88
- 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.
73
+ ## Core concepts
89
74
 
90
- ### SSR - one class, zero config
75
+ ### Runtime Agnostic Templates (RAT)
91
76
 
92
- Server rendering doesn't need a virtual DOM, a reconciler, or framework-specific packages:
77
+ 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.
93
78
 
94
79
  ```js
95
- import { SSR } from '@symbiotejs/symbiote/node/SSR.js';
96
-
97
- await SSR.init(); // patches globals with linkedom
98
- await import('./my-app.js'); // components register normally
80
+ // Separate file: my-component.template.js
81
+ import { html } from '@symbiotejs/symbiote';
99
82
 
100
- let html = await SSR.processHtml('<my-app></my-app>');
101
- SSR.destroy();
83
+ export default html`
84
+ <h1>{{title}}</h1>
85
+ <button ${{onclick: 'doSomething'}}>Go</button>
86
+ `;
102
87
  ```
103
88
 
104
- 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).
105
-
106
- ### How it compares
107
-
108
- | | **Symbiote.js** | **Next.js (React)** | **Lit** (`@lit-labs/ssr`) |
109
- |--|----------------|---------------------|----|
110
- | **Isomorphic code** | Same code, `isoMode` auto-detects | Server Components vs Client Components split | Same code, but load-order constraints |
111
- | **Hydration** | Binding-based - attaches to existing DOM, no diffing | `hydrateRoot()` - must produce identical output or errors | Requires `ssr-client` + hydrate support module |
112
- | **Packages** | 1 module + `linkedom` peer dep | Full framework buy-in | 3 packages: `ssr`, `ssr-client`, `ssr-dom-shim` |
113
- | **Streaming** | `renderToStream()` async generator | `renderToPipeableStream()` | Iterable `RenderResult` |
114
- | **Mismatch handling** | Not needed - bindings attach to whatever DOM exists | Hard errors if server/client output differs | N/A |
115
- | **Template output** | Clean HTML with `bind=` attributes | HTML with framework markers | HTML with `<!--lit-part-->` comment markers |
116
- | **Lock-in** | None - standard Web Components | Full framework commitment | Lit-specific, but Web Components |
117
-
118
- **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.
89
+ The `html` function supports two interpolation modes:
119
90
 
120
- ## Core concepts
91
+ - An object creates a reactive binding: `${{onclick: 'handler'}}`
92
+ - A string or number uses native concatenation: `${pageTitle}`
121
93
 
122
94
  ### Reactive state
123
95
 
@@ -135,65 +107,37 @@ TodoItem.template = html`
135
107
  `;
136
108
  ```
137
109
 
138
- 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:
110
+ 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:
139
111
 
140
112
  ```js
141
113
  document.querySelector('my-counter').$.count = 42;
142
114
  ```
143
115
 
144
- This makes it easy to control Symbiote-based widgets and microfrontends from any host application - no framework adapters, just DOM.
145
-
146
- ### Templates
147
-
148
- Templates are plain HTML strings - context-free, easy to test, easy to move between files:
149
-
150
- ```js
151
- // Separate file: my-component.template.js
152
- import { html } from '@symbiotejs/symbiote';
153
-
154
- export default html`
155
- <h1>{{title}}</h1>
156
- <button ${{onclick: 'doSomething'}}>Go</button>
157
- `;
158
- ```
159
-
160
- The `html` function supports two interpolation modes:
161
- - **Object** → reactive binding: `${{onclick: 'handler'}}`
162
- - **String/number** → native concatenation: `${pageTitle}`
116
+ Any host application can control a Symbiote.js widget or microfrontend through the DOM API. It does not need a framework adapter.
163
117
 
164
118
  ### Itemize (dynamic reactive lists)
165
119
 
166
- Render lists from data arrays with efficient updates:
120
+ Render lists from data arrays or objects with efficient updates:
167
121
  ```js
168
122
  class TaskList extends Symbiote {
169
123
  tasks = [
170
124
  { name: 'Buy groceries' },
171
125
  { name: 'Write docs' },
172
126
  ];
173
- init$ = {
174
- // Needs to be defined in init$ for pop-up binding to work
175
- onItemClick: () => {
176
- console.log('clicked!');
177
- },
178
- }
179
127
  }
180
128
 
181
129
  TaskList.template = html`
182
- <div itemize="tasks">
130
+ <ul itemize="tasks">
183
131
  <template>
184
- <div ${{onclick: '^onItemClick'}}>{{name}}</div>
132
+ <li>{{name}}</li>
185
133
  </template>
186
- </div>
134
+ </ul>
187
135
  `;
188
136
  ```
189
137
 
190
- 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$`.
191
-
192
- > **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.
193
-
194
138
  ### Pop-up binding (`^`)
195
139
 
196
- 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$()`):
140
+ 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$()`):
197
141
 
198
142
  ```html
199
143
  <!-- Text binding to parent property: -->
@@ -203,14 +147,12 @@ The `^` prefix works in any nested component template - it walks up the DOM tree
203
147
  <button ${{onclick: '^parentHandler'}}>Click</button>
204
148
  ```
205
149
 
206
- > **Note:** Class property fallbacks are not checked by the `^` walk - the parent must define the property in `init$`.
207
-
208
- ### Named data contexts
150
+ ### Namespace bindings and named contexts
209
151
 
210
- Share state across components without prop drilling:
152
+ 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:
211
153
 
212
154
  ```js
213
- import { PubSub } from '@symbiotejs/symbiote';
155
+ import { PubSub, html } from '@symbiotejs/symbiote';
214
156
 
215
157
  PubSub.registerCtx({
216
158
  user: 'Alex',
@@ -219,11 +161,14 @@ PubSub.registerCtx({
219
161
 
220
162
  // Any component can read/write:
221
163
  this.$['APP/user'] = 'New name';
164
+
165
+ // Any template can use property directly:
166
+ let template = html`<h2>{{APP/user}}</h2>`;
222
167
  ```
223
168
 
224
169
  ### Shared context (`*`)
225
170
 
226
- 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:
171
+ 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:
227
172
 
228
173
  ```html
229
174
  <upload-btn ctx="gallery"></upload-btn>
@@ -249,13 +194,12 @@ class StatusBar extends Symbiote {
249
194
  }
250
195
  ```
251
196
 
252
- 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.
253
-
254
- The context name can also be inherited via CSS custom property `--ctx`, enabling layout-driven grouping.
197
+ 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.
255
198
 
256
- ### Routing (optional module)
199
+ ### Application routing
257
200
 
258
201
  ```js
202
+ // Import optional module:
259
203
  import { AppRouter } from '@symbiotejs/symbiote/core/AppRouter.js';
260
204
 
261
205
  AppRouter.initRoutingCtx('R', {
@@ -265,27 +209,11 @@ AppRouter.initRoutingCtx('R', {
265
209
  });
266
210
  ```
267
211
 
268
- ### Exit animations
269
-
270
- CSS-driven transitions with zero JS animation code:
271
-
272
- ```css
273
- task-item {
274
- opacity: 1;
275
- transition: opacity 0.3s;
276
-
277
- @starting-style { opacity: 0; } /* enter */
278
- &[leaving] { opacity: 0; } /* exit */
279
- }
280
- ```
281
-
282
- `animateOut(el)` sets `[leaving]`, waits for `transitionend`, then removes. Itemize uses this automatically.
212
+ ### CSS styling
283
213
 
284
- ### Styling
214
+ 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.
285
215
 
286
- Shadow DOM is **optional** in Symbiote - use it when you need isolation, skip it when you don't. This gives full flexibility:
287
-
288
- **Light DOM** - style components with regular CSS, no barriers:
216
+ Light DOM components use regular CSS:
289
217
 
290
218
  ```js
291
219
  MyComponent.rootStyles = css`
@@ -298,7 +226,9 @@ MyComponent.rootStyles = css`
298
226
  `;
299
227
  ```
300
228
 
301
- **Shadow DOM** - opt-in isolation when needed:
229
+ Symbiote.js applies this style to the nearest containing shadow root, when one exists, or to the document.
230
+
231
+ Use Shadow DOM for opt-in isolation:
302
232
 
303
233
  ```js
304
234
  class Isolated extends Symbiote {}
@@ -309,11 +239,11 @@ Isolated.shadowStyles = css`
309
239
  `;
310
240
  ```
311
241
 
312
- 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.
242
+ 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.
313
243
 
314
- ### CSS Data Binding
244
+ ### CSS data
315
245
 
316
- Components can read CSS custom properties as reactive state via `cssInit$`:
246
+ Components can read CSS custom property values to initiate reactive state:
317
247
 
318
248
  ```css
319
249
  my-widget {
@@ -329,31 +259,23 @@ MyWidget.template = html`
329
259
  `;
330
260
  ```
331
261
 
332
- 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.
333
-
334
262
  ## Best for
335
263
 
336
- - **Complex widgets** embedded in any host application
337
- - **Low-code HTML-based solutions** - simple declarative everything
338
- - **Micro frontends** - standard custom elements, no framework coupling
339
- - **Reusable component libraries** - works in React, Vue, Angular, or plain HTML
340
- - **SSR-powered apps** - lightweight server rendering without framework lock-in
341
- - **Framework-agnostic solutions** - one codebase, any context
342
- - **Modern AI-first web** - expose the application state to WebMCP tools automatically
343
-
344
- ## Browser support
345
-
346
- All modern browsers: Chrome, Firefox, Safari, Edge, Opera.
264
+ - Complex widgets embedded in any host application
265
+ - Low-code, HTML-based interfaces with declarative bindings for UI, data, and actions
266
+ - Microfrontends built from standard Custom Elements without framework coupling
267
+ - Reusable component libraries for React, Vue, Angular, or plain HTML
268
+ - SSR applications that need lightweight server rendering without framework lock-in
269
+ - Framework-agnostic solutions that reuse one codebase across contexts
270
+ - Agent-facing web applications that expose state and actions through WebMCP
347
271
 
348
- ## Docs & Examples
272
+ ## Docs and examples
349
273
 
350
274
  - [Documentation](https://github.com/symbiotejs/symbiote.js/blob/main/docs/README.md)
351
- - [Lit vs Symbiote.js](https://github.com/symbiotejs/symbiote.js/blob/main/docs/lit-vs-symbiote.md) - Side-by-side comparison
352
- - [Live Examples](https://rnd-pro.com/symbiote/3x/examples/) - Interactive Code Playground
353
- - [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
354
- - [AI / llms.txt](https://rnd-pro.com/symbiote/llms.txt) — index for AI tools
355
- - [Full docs (single file)](https://rnd-pro.com/symbiote/llms-full.txt) — complete merged reference for AI context
356
- - [Changelog](https://github.com/symbiotejs/symbiote.js/blob/main/CHANGELOG.md)
275
+ - [Live examples](https://rnd-pro.com/symbiote/3x/examples/): interactive code playground
276
+ - [JSDA-Kit](https://github.com/rnd-pro/jsda-kit): companion tooling for the server, SSG, bundling, import maps, and native Symbiote.js SSR integration
277
+ - [AI / llms.txt](https://rnd-pro.com/symbiote/llms.txt): index for AI tools
278
+ - [Full docs (single file)](https://rnd-pro.com/symbiote/llms-full.txt): complete merged reference for AI context
357
279
 
358
280
  ## Related articles
359
281
 
@@ -362,8 +284,8 @@ All modern browsers: Chrome, Firefox, Safari, Edge, Opera.
362
284
  - [Symbiote.js vs Lit](https://dev.to/foxeyes/lit-vs-symbiotejs-22gj)
363
285
  - [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)
364
286
 
365
- **Questions or proposals? Welcome to [Symbiote Discussions](https://github.com/symbiotejs/symbiote.js/discussions)!** ❤️
287
+ Questions and proposals are welcome in [Symbiote Discussions](https://github.com/symbiotejs/symbiote.js/discussions).
366
288
 
367
289
  ---
368
290
 
369
- © [rnd-pro.com](https://rnd-pro.com) - MIT License
291
+ © [rnd-pro.com](https://rnd-pro.com), MIT License
package/core/webmcp.js CHANGED
@@ -45,6 +45,9 @@ import { parseProp } from './parseProp.js';
45
45
  const REGISTRY_UID = Symbol.for('symbiote.webmcp.registry');
46
46
  let ownerIdCount = 0;
47
47
 
48
+ /** @type {WeakMap<object, (input: Object) => any>} */
49
+ let toolExecutors = new WeakMap();
50
+
48
51
  /** @type {WeakMap<object, Array<{remove: Function}>>} */
49
52
  let ownerDeps = new WeakMap();
50
53
  /** @type {WeakSet<typeof Symbiote>} */
@@ -82,6 +85,29 @@ function errorResponse(error) {
82
85
  };
83
86
  }
84
87
 
88
+ function unavailableTool(name) {
89
+ return errorResponse(new Error(`WebMCP tool "${name}" is not available.`));
90
+ }
91
+
92
+ function executeEntry(entry, input, name = entry?.name) {
93
+ let executor = entry && toolExecutors.get(entry);
94
+ if (!entry?.active || !executor) {
95
+ return unavailableTool(name);
96
+ }
97
+ try {
98
+ let result = executor(input || {});
99
+ return result?.then ? Promise.resolve(result).catch(errorResponse) : result;
100
+ } catch (error) {
101
+ return errorResponse(error);
102
+ }
103
+ }
104
+
105
+ function deactivateEntry(entry) {
106
+ entry.active = false;
107
+ toolExecutors.delete(entry);
108
+ entry.controller?.abort();
109
+ }
110
+
85
111
  function textResponse(text) {
86
112
  return {
87
113
  content: [{
@@ -348,7 +374,7 @@ function unregisterToolName(publicName) {
348
374
  return;
349
375
  }
350
376
  let entry = tools.read(publicName);
351
- entry?.controller?.abort();
377
+ deactivateEntry(entry);
352
378
  tools.delete(publicName);
353
379
  }
354
380
 
@@ -356,7 +382,7 @@ function updateOwnerEntry(ownerIdVal, entry) {
356
382
  webMCPRegistry.store.owners.add(ownerIdVal, entry, true);
357
383
  }
358
384
 
359
- function registerNativeTool(publicName, toolEntry, descriptor, owner, executor) {
385
+ function registerNativeTool(publicName, toolEntry, descriptor) {
360
386
  let modelContext = getModelContext();
361
387
  setDiagnostic('apiAvailable', !!modelContext);
362
388
  if (!modelContext) {
@@ -371,15 +397,7 @@ function registerNativeTool(publicName, toolEntry, descriptor, owner, executor)
371
397
  description: toolEntry.description,
372
398
  inputSchema: toolEntry.inputSchema,
373
399
  execute(input = {}) {
374
- try {
375
- let result = executor(input || {});
376
- if (result?.then) {
377
- return result.catch(errorResponse);
378
- }
379
- return result;
380
- } catch (e) {
381
- return errorResponse(e);
382
- }
400
+ return executeEntry(toolEntry, input);
383
401
  },
384
402
  };
385
403
  if (descriptor.annotations) {
@@ -421,7 +439,13 @@ function makeEntryWithComponentDescription(publicName, key, descriptor, owner, e
421
439
  nativeActive: false,
422
440
  controller: null,
423
441
  };
424
- let native = registerNativeTool(publicName, entry, descriptor, owner, executor);
442
+ toolExecutors.set(entry, (input) => {
443
+ if ((isElementOwner(owner) && !owner.isConnected) || !shouldRegister(descriptor, owner)) {
444
+ return unavailableTool(publicName);
445
+ }
446
+ return executor(input);
447
+ });
448
+ let native = registerNativeTool(publicName, entry, descriptor);
425
449
  entry.controller = native.controller;
426
450
  entry.nativeActive = native.nativeActive;
427
451
  return entry;
@@ -471,10 +495,13 @@ function createAutoDesired(owner, key, eventBinding = null) {
471
495
  throw new Error(`Handler "${key}" is not available on <${tagName}>.`);
472
496
  }
473
497
  let result = handler.call(owner, syntheticEvent(eventBinding?.el));
474
- let suffix = result ? `: ${result}` : '';
475
- return textResponse(
476
- `Response status - ok${suffix}\nDetails: ${JSON.stringify(stateSnapshot(owner))}`
477
- );
498
+ let respond = (value) => {
499
+ let suffix = value ? `: ${value}` : '';
500
+ return textResponse(
501
+ `Response status - ok${suffix}\nDetails: ${JSON.stringify(stateSnapshot(owner))}`
502
+ );
503
+ };
504
+ return result?.then ? Promise.resolve(result).then(respond) : respond(result);
478
505
  },
479
506
  });
480
507
  return {
@@ -667,6 +694,8 @@ export function registerWebMCPTool(owner, key, descriptor) {
667
694
  return entry.then((resolvedEntry) => {
668
695
  if (isCurrentOwnerVersion(owner, version)) {
669
696
  webMCPRegistry.store.tools.add(publicName, resolvedEntry, true);
697
+ } else {
698
+ deactivateEntry(resolvedEntry);
670
699
  }
671
700
  return resolvedEntry;
672
701
  }).catch((e) => {
@@ -782,6 +811,18 @@ export function getActiveWebMCPTools() {
782
811
  return Object.keys(tools).map((name) => serializeEntry(tools[name]));
783
812
  }
784
813
 
814
+ /**
815
+ * Invoke a currently registered tool without requiring native browser WebMCP.
816
+ * Input validation and transport authorization belong to the caller.
817
+ * @param {string} name
818
+ * @param {Object} [input]
819
+ * @returns {any | Promise<any>}
820
+ */
821
+ export function executeWebMCPTool(name, input = {}) {
822
+ let tools = webMCPRegistry.store.tools;
823
+ return executeEntry(tools.has(name) ? tools.read(name) : undefined, input, name);
824
+ }
825
+
785
826
  /** @param {typeof Symbiote} [SymbioteClass] */
786
827
  export function installWebMCP(SymbioteClass = Symbiote) {
787
828
  if (installedClasses.has(SymbioteClass)) {
@@ -825,4 +866,5 @@ export default {
825
866
  unregisterWebMCPTools,
826
867
  syncWebMCPTools,
827
868
  getActiveWebMCPTools,
869
+ executeWebMCPTool,
828
870
  };
package/docs/README.md CHANGED
@@ -29,7 +29,7 @@
29
29
 
30
30
  ## Features
31
31
 
32
- - [**WebMCP Experimental**](./webmcp.md) — Expose live UI state and handlers as browser-native tools
32
+ - [**WebMCP**](./webmcp.md) — Expose live UI state and handlers as browser-native tools
33
33
  - [**Routing**](./routing.md) — SPA routing with path patterns, guards, lazy loading
34
34
  - [**SSR**](./ssr.md) — Server-side rendering, streaming, hydration
35
35
  - [**SSR and Your Server Setup**](./ssr-server.md) — Static build, streaming, Express or Fastify
@@ -41,19 +41,13 @@
41
41
  - [**TypeScript**](./typescript.md) — JSDoc types, TypeScript usage, and hybrid template checks
42
42
  - [**Security**](./security.md) — Trusted Types and CSP compliance
43
43
 
44
- ## Migration
45
-
46
- - [**2.x → 3.x Migration Guide**](./migration-2x-to-3x.md) — Breaking changes and upgrade path
47
-
48
44
  ## Additional Resources
49
45
 
50
- - [Lit vs Symbiote.js](./lit-vs-symbiote.md) — Side-by-side comparison
51
46
  - [Live Examples](https://rnd-pro.com/symbiote/3x/examples/) - Interactive Code Playground
52
47
  - [Common Mistakes](./common-mistakes.md) — Patterns that frequently cause bugs
53
48
  - [Examples](./examples.md) — 26 complete working examples
54
49
  - [llms.txt](https://rnd-pro.com/symbiote/llms.txt) — index for AI tools
55
50
  - [llms-full.txt](https://rnd-pro.com/symbiote/llms-full.txt) — complete merged reference for AI context
56
- - [Changelog](../CHANGELOG.md)
57
51
  - [npm](https://www.npmjs.com/package/@symbiotejs/symbiote)
58
52
  - [GitHub Discussions](https://github.com/symbiotejs/symbiote.js/discussions)
59
53
 
@@ -38,7 +38,7 @@ my-item {
38
38
 
39
39
  ## Itemize integration
40
40
 
41
- Both itemize processors use `animateOut` automatically for item removal. Items with CSS `transition` + `[leaving]` styles will animate out before being removed from the DOM:
41
+ Itemize processors use `animateOut` automatically for item removal. Items with CSS `transition` + `[leaving]` styles will animate out before being removed from the DOM:
42
42
  ```css
43
43
  user-card {
44
44
  opacity: 1;
@@ -22,7 +22,7 @@ class MyComponent extends Symbiote {}
22
22
  MyComponent.template = html`<h1>{{@attribute-name}}</h1>`;
23
23
  ```
24
24
 
25
- Then use it as an attribute in markup:
25
+ Then use it as an component's attribute in markup:
26
26
  ```html
27
27
  <my-component attribute-name="attribute value"></my-component>
28
28
  ```
@@ -46,7 +46,7 @@ MyComponent.observedAttributes = [
46
46
 
47
47
  ## `bindAttributes()` static method
48
48
 
49
- Bind attributes to property values directly:
49
+ Reflect attribute values to property values:
50
50
  ```js
51
51
  class MyComponent extends Symbiote {
52
52
 
@@ -243,7 +243,69 @@ Named external contexts (`CTX/prop`) are different: they are registered globally
243
243
 
244
244
  ---
245
245
 
246
- ## 10. Treating `init$` as a plain object
246
+ ## 10. Using `{{prop}}` binding syntax inside tag definitions
247
+
248
+ `{{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.
249
+
250
+ ```html
251
+ <!-- WRONG — {{}} syntax does not work inside tag definitions -->
252
+ <div class="{{APP/theme}}">...</div>
253
+ <img src="{{imageUrl}}">
254
+ <button onclick="{{onAction}}">Go</button>
255
+
256
+ <!-- CORRECT — use ${{}} binding object inside the tag -->
257
+ <div ${{'@class': 'APP/theme'}}>...</div>
258
+ <img ${{'@src': 'imageUrl'}}>
259
+ <button ${{onclick: 'onAction'}}>Go</button>
260
+ <div ${{'style.color': 'colorProp'}}>...</div>
261
+
262
+ <!-- CORRECT — or use the bind attribute string syntax -->
263
+ <div bind="@class: APP/theme">...</div>
264
+ <img bind="@src: imageUrl">
265
+ <button bind="onclick: onAction">Go</button>
266
+
267
+ <!-- CORRECT — {{}} works fine in text node content -->
268
+ <h1>Hello, {{userName}}!</h1>
269
+ <p>Theme: {{APP/theme}}</p>
270
+ ```
271
+
272
+ ---
273
+
274
+ ## 11. Expecting two-way data binding
275
+
276
+ 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.
277
+
278
+ ```js
279
+ // WRONG — expecting the binding to also update state on user input
280
+ MyComponent.template = html`
281
+ <input ${{value: 'query'}}>
282
+ `;
283
+
284
+ // CORRECT — handle the input event and write back to state
285
+ class MyComponent extends Symbiote {
286
+ init$ = { query: '' }
287
+ }
288
+
289
+ MyComponent.template = html`
290
+ <input
291
+ ${{value: 'query', oninput: 'onInput'}}
292
+ >
293
+ `;
294
+ ```
295
+ ```js
296
+ class MyComponent extends Symbiote {
297
+ init$ = {
298
+ query: '',
299
+ onInput: (e) => { this.$.query = e.target.value; },
300
+ }
301
+ }
302
+ ```
303
+
304
+ This is intentional — explicit event handling keeps data flow predictable and avoids the hidden side effects that two-way binding can introduce.
305
+
306
+ ---
307
+
308
+ ## 12. Treating `init$` as a plain object
247
309
 
248
310
  `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.
249
311