@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 +75 -153
- package/core/webmcp.js +58 -16
- package/docs/README.md +1 -7
- package/docs/animations.md +1 -1
- package/docs/attributes.md +2 -2
- package/docs/common-mistakes.md +63 -1
- package/docs/context.md +212 -73
- package/docs/ecosystem.md +0 -3
- package/docs/llms-index.md +0 -1
- package/docs/webmcp.md +19 -0
- package/llms-full.txt +372 -230
- package/llms.txt +0 -1
- package/package.json +4 -4
- package/scripts/build-llms.js +0 -2
- package/types/core/webmcp.d.ts +2 -0
- package/types/core/webmcp.d.ts.map +1 -1
- package/CHANGELOG.md +0 -372
- package/docs/lit-vs-symbiote.md +0 -200
- package/docs/migration-2x-to-3x.md +0 -171
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
|
-
|
|
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
|
|
12
|
+
## Why Symbiote.js?
|
|
13
13
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
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
|
-
-
|
|
22
|
-
-
|
|
23
|
-
-
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
-
|
|
28
|
-
-
|
|
29
|
-
-
|
|
30
|
-
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
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
|
-
###
|
|
75
|
+
### Runtime Agnostic Templates (RAT)
|
|
91
76
|
|
|
92
|
-
|
|
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
|
-
|
|
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
|
-
|
|
101
|
-
|
|
83
|
+
export default html`
|
|
84
|
+
<h1>{{title}}</h1>
|
|
85
|
+
<button ${{onclick: 'doSomething'}}>Go</button>
|
|
86
|
+
`;
|
|
102
87
|
```
|
|
103
88
|
|
|
104
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
<
|
|
130
|
+
<ul itemize="tasks">
|
|
183
131
|
<template>
|
|
184
|
-
<
|
|
132
|
+
<li>{{name}}</li>
|
|
185
133
|
</template>
|
|
186
|
-
</
|
|
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
|
-
|
|
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
|
-
|
|
207
|
-
|
|
208
|
-
### Named data contexts
|
|
150
|
+
### Namespace bindings and named contexts
|
|
209
151
|
|
|
210
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
###
|
|
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
|
-
###
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
244
|
+
### CSS data
|
|
315
245
|
|
|
316
|
-
Components can read CSS custom
|
|
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
|
-
-
|
|
337
|
-
-
|
|
338
|
-
-
|
|
339
|
-
-
|
|
340
|
-
-
|
|
341
|
-
-
|
|
342
|
-
-
|
|
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
|
|
272
|
+
## Docs and examples
|
|
349
273
|
|
|
350
274
|
- [Documentation](https://github.com/symbiotejs/symbiote.js/blob/main/docs/README.md)
|
|
351
|
-
- [
|
|
352
|
-
- [
|
|
353
|
-
- [
|
|
354
|
-
- [
|
|
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
|
-
|
|
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)
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
475
|
-
|
|
476
|
-
|
|
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
|
|
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
|
|
package/docs/animations.md
CHANGED
|
@@ -38,7 +38,7 @@ my-item {
|
|
|
38
38
|
|
|
39
39
|
## Itemize integration
|
|
40
40
|
|
|
41
|
-
|
|
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;
|
package/docs/attributes.md
CHANGED
|
@@ -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
|
-
|
|
49
|
+
Reflect attribute values to property values:
|
|
50
50
|
```js
|
|
51
51
|
class MyComponent extends Symbiote {
|
|
52
52
|
|
package/docs/common-mistakes.md
CHANGED
|
@@ -243,7 +243,69 @@ Named external contexts (`CTX/prop`) are different: they are registered globally
|
|
|
243
243
|
|
|
244
244
|
---
|
|
245
245
|
|
|
246
|
-
## 10.
|
|
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
|
|