@symbiotejs/symbiote 3.8.2 → 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 +72 -63
- package/core/webmcp.js +58 -16
- package/docs/README.md +1 -1
- package/docs/webmcp.md +19 -0
- package/llms-full.txt +91 -63
- package/package.json +4 -3
- package/types/core/webmcp.d.ts +2 -0
- package/types/core/webmcp.d.ts.map +1 -1
package/README.md
CHANGED
|
@@ -7,29 +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
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
12
|
+
## Why Symbiote.js?
|
|
13
|
+
|
|
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.
|
|
16
23
|
|
|
17
24
|
## What's new in v3.x?
|
|
18
25
|
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
-
|
|
22
|
-
-
|
|
23
|
-
-
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
-
|
|
28
|
-
-
|
|
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.
|
|
29
36
|
|
|
30
37
|
## Quick start
|
|
31
38
|
|
|
32
|
-
|
|
39
|
+
Run this example directly in a browser without installing the package:
|
|
33
40
|
|
|
34
41
|
```html
|
|
35
42
|
<script type="module">
|
|
@@ -53,7 +60,7 @@ No install needed - run this directly in a browser:
|
|
|
53
60
|
<my-counter></my-counter>
|
|
54
61
|
```
|
|
55
62
|
|
|
56
|
-
|
|
63
|
+
For npm-based projects:
|
|
57
64
|
|
|
58
65
|
```bash
|
|
59
66
|
npm i @symbiotejs/symbiote
|
|
@@ -65,6 +72,25 @@ import Symbiote, { html, css } from '@symbiotejs/symbiote';
|
|
|
65
72
|
|
|
66
73
|
## Core concepts
|
|
67
74
|
|
|
75
|
+
### Runtime Agnostic Templates (RAT)
|
|
76
|
+
|
|
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.
|
|
78
|
+
|
|
79
|
+
```js
|
|
80
|
+
// Separate file: my-component.template.js
|
|
81
|
+
import { html } from '@symbiotejs/symbiote';
|
|
82
|
+
|
|
83
|
+
export default html`
|
|
84
|
+
<h1>{{title}}</h1>
|
|
85
|
+
<button ${{onclick: 'doSomething'}}>Go</button>
|
|
86
|
+
`;
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
The `html` function supports two interpolation modes:
|
|
90
|
+
|
|
91
|
+
- An object creates a reactive binding: `${{onclick: 'handler'}}`
|
|
92
|
+
- A string or number uses native concatenation: `${pageTitle}`
|
|
93
|
+
|
|
68
94
|
### Reactive state
|
|
69
95
|
|
|
70
96
|
```js
|
|
@@ -81,31 +107,13 @@ TodoItem.template = html`
|
|
|
81
107
|
`;
|
|
82
108
|
```
|
|
83
109
|
|
|
84
|
-
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:
|
|
85
111
|
|
|
86
112
|
```js
|
|
87
113
|
document.querySelector('my-counter').$.count = 42;
|
|
88
114
|
```
|
|
89
115
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
### Templates
|
|
93
|
-
|
|
94
|
-
Templates are plain HTML strings - runtime-agnostic, easy to test, easy to move between files:
|
|
95
|
-
|
|
96
|
-
```js
|
|
97
|
-
// Separate file: my-component.template.js
|
|
98
|
-
import { html } from '@symbiotejs/symbiote';
|
|
99
|
-
|
|
100
|
-
export default html`
|
|
101
|
-
<h1>{{title}}</h1>
|
|
102
|
-
<button ${{onclick: 'doSomething'}}>Go</button>
|
|
103
|
-
`;
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
The `html` function supports two interpolation modes:
|
|
107
|
-
- **Object** → reactive binding: `${{onclick: 'handler'}}`
|
|
108
|
-
- **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.
|
|
109
117
|
|
|
110
118
|
### Itemize (dynamic reactive lists)
|
|
111
119
|
|
|
@@ -129,7 +137,7 @@ TaskList.template = html`
|
|
|
129
137
|
|
|
130
138
|
### Pop-up binding (`^`)
|
|
131
139
|
|
|
132
|
-
|
|
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$()`):
|
|
133
141
|
|
|
134
142
|
```html
|
|
135
143
|
<!-- Text binding to parent property: -->
|
|
@@ -139,9 +147,10 @@ The `^` prefix works in any nested component template - it walks up the DOM tree
|
|
|
139
147
|
<button ${{onclick: '^parentHandler'}}>Click</button>
|
|
140
148
|
```
|
|
141
149
|
|
|
142
|
-
###
|
|
150
|
+
### Namespace bindings and named contexts
|
|
151
|
+
|
|
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:
|
|
143
153
|
|
|
144
|
-
Share state across components without prop drilling:
|
|
145
154
|
```js
|
|
146
155
|
import { PubSub, html } from '@symbiotejs/symbiote';
|
|
147
156
|
|
|
@@ -159,7 +168,7 @@ let template = html`<h2>{{APP/user}}</h2>`;
|
|
|
159
168
|
|
|
160
169
|
### Shared context (`*`)
|
|
161
170
|
|
|
162
|
-
|
|
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:
|
|
163
172
|
|
|
164
173
|
```html
|
|
165
174
|
<upload-btn ctx="gallery"></upload-btn>
|
|
@@ -185,7 +194,7 @@ class StatusBar extends Symbiote {
|
|
|
185
194
|
}
|
|
186
195
|
```
|
|
187
196
|
|
|
188
|
-
All three components access the same `*files` state
|
|
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.
|
|
189
198
|
|
|
190
199
|
### Application routing
|
|
191
200
|
|
|
@@ -200,11 +209,11 @@ AppRouter.initRoutingCtx('R', {
|
|
|
200
209
|
});
|
|
201
210
|
```
|
|
202
211
|
|
|
203
|
-
### CSS
|
|
212
|
+
### CSS styling
|
|
204
213
|
|
|
205
|
-
Shadow DOM is
|
|
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.
|
|
206
215
|
|
|
207
|
-
|
|
216
|
+
Light DOM components use regular CSS:
|
|
208
217
|
|
|
209
218
|
```js
|
|
210
219
|
MyComponent.rootStyles = css`
|
|
@@ -217,9 +226,9 @@ MyComponent.rootStyles = css`
|
|
|
217
226
|
`;
|
|
218
227
|
```
|
|
219
228
|
|
|
220
|
-
|
|
229
|
+
Symbiote.js applies this style to the nearest containing shadow root, when one exists, or to the document.
|
|
221
230
|
|
|
222
|
-
|
|
231
|
+
Use Shadow DOM for opt-in isolation:
|
|
223
232
|
|
|
224
233
|
```js
|
|
225
234
|
class Isolated extends Symbiote {}
|
|
@@ -230,9 +239,9 @@ Isolated.shadowStyles = css`
|
|
|
230
239
|
`;
|
|
231
240
|
```
|
|
232
241
|
|
|
233
|
-
|
|
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.
|
|
234
243
|
|
|
235
|
-
### CSS
|
|
244
|
+
### CSS data
|
|
236
245
|
|
|
237
246
|
Components can read CSS custom property values to initiate reactive state:
|
|
238
247
|
|
|
@@ -252,21 +261,21 @@ MyWidget.template = html`
|
|
|
252
261
|
|
|
253
262
|
## Best for
|
|
254
263
|
|
|
255
|
-
-
|
|
256
|
-
-
|
|
257
|
-
-
|
|
258
|
-
-
|
|
259
|
-
-
|
|
260
|
-
-
|
|
261
|
-
-
|
|
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
|
|
262
271
|
|
|
263
|
-
## Docs
|
|
272
|
+
## Docs and examples
|
|
264
273
|
|
|
265
274
|
- [Documentation](https://github.com/symbiotejs/symbiote.js/blob/main/docs/README.md)
|
|
266
|
-
- [Live
|
|
267
|
-
- [JSDA-Kit](https://github.com/rnd-pro/jsda-kit)
|
|
268
|
-
- [AI / llms.txt](https://rnd-pro.com/symbiote/llms.txt)
|
|
269
|
-
- [Full docs (single file)](https://rnd-pro.com/symbiote/llms-full.txt)
|
|
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
|
|
270
279
|
|
|
271
280
|
## Related articles
|
|
272
281
|
|
|
@@ -275,8 +284,8 @@ MyWidget.template = html`
|
|
|
275
284
|
- [Symbiote.js vs Lit](https://dev.to/foxeyes/lit-vs-symbiotejs-22gj)
|
|
276
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)
|
|
277
286
|
|
|
278
|
-
|
|
287
|
+
Questions and proposals are welcome in [Symbiote Discussions](https://github.com/symbiotejs/symbiote.js/discussions).
|
|
279
288
|
|
|
280
289
|
---
|
|
281
290
|
|
|
282
|
-
© [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
|
package/docs/webmcp.md
CHANGED
|
@@ -137,6 +137,25 @@ class UserCard extends Symbiote {
|
|
|
137
137
|
|
|
138
138
|
The returned text is appended to each component-owned tool description.
|
|
139
139
|
|
|
140
|
+
## Direct Invocation
|
|
141
|
+
|
|
142
|
+
Applications can discover and invoke tools through public APIs without native browser WebMCP support:
|
|
143
|
+
|
|
144
|
+
```js
|
|
145
|
+
import { getActiveWebMCPTools, executeWebMCPTool } from '@symbiotejs/symbiote/webmcp';
|
|
146
|
+
|
|
147
|
+
let tools = getActiveWebMCPTools();
|
|
148
|
+
let result = await executeWebMCPTool('submit_order_in_webmcp-panel', { note: 'Ready' });
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
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.
|
|
152
|
+
|
|
153
|
+
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.
|
|
154
|
+
|
|
155
|
+
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.
|
|
156
|
+
|
|
157
|
+
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.
|
|
158
|
+
|
|
140
159
|
## Notes
|
|
141
160
|
|
|
142
161
|
- This is an experimental release. Names, metadata shape, and browser APIs may change.
|
package/llms-full.txt
CHANGED
|
@@ -2,29 +2,36 @@
|
|
|
2
2
|
|
|
3
3
|
<img src="https://rnd-pro.com/svg/symbiote/index.svg" width="200" alt="Symbiote.js">
|
|
4
4
|
|
|
5
|
-
|
|
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
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
7
|
+
## Why Symbiote.js?
|
|
8
|
+
|
|
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.
|
|
11
18
|
|
|
12
19
|
## What's new in v3.x?
|
|
13
20
|
|
|
14
|
-
-
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
-
|
|
22
|
-
-
|
|
23
|
-
-
|
|
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.
|
|
24
31
|
|
|
25
32
|
## Quick start
|
|
26
33
|
|
|
27
|
-
|
|
34
|
+
Run this example directly in a browser without installing the package:
|
|
28
35
|
|
|
29
36
|
```html
|
|
30
37
|
<script type="module">
|
|
@@ -48,7 +55,7 @@ No install needed - run this directly in a browser:
|
|
|
48
55
|
<my-counter></my-counter>
|
|
49
56
|
```
|
|
50
57
|
|
|
51
|
-
|
|
58
|
+
For npm-based projects:
|
|
52
59
|
|
|
53
60
|
```bash
|
|
54
61
|
npm i @symbiotejs/symbiote
|
|
@@ -60,6 +67,25 @@ import Symbiote, { html, css } from '@symbiotejs/symbiote';
|
|
|
60
67
|
|
|
61
68
|
## Core concepts
|
|
62
69
|
|
|
70
|
+
### Runtime Agnostic Templates (RAT)
|
|
71
|
+
|
|
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.
|
|
73
|
+
|
|
74
|
+
```js
|
|
75
|
+
// Separate file: my-component.template.js
|
|
76
|
+
import { html } from '@symbiotejs/symbiote';
|
|
77
|
+
|
|
78
|
+
export default html`
|
|
79
|
+
<h1>{{title}}</h1>
|
|
80
|
+
<button ${{onclick: 'doSomething'}}>Go</button>
|
|
81
|
+
`;
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
The `html` function supports two interpolation modes:
|
|
85
|
+
|
|
86
|
+
- An object creates a reactive binding: `${{onclick: 'handler'}}`
|
|
87
|
+
- A string or number uses native concatenation: `${pageTitle}`
|
|
88
|
+
|
|
63
89
|
### Reactive state
|
|
64
90
|
|
|
65
91
|
```js
|
|
@@ -76,31 +102,13 @@ TodoItem.template = html`
|
|
|
76
102
|
`;
|
|
77
103
|
```
|
|
78
104
|
|
|
79
|
-
State changes update
|
|
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:
|
|
80
106
|
|
|
81
107
|
```js
|
|
82
108
|
document.querySelector('my-counter').$.count = 42;
|
|
83
109
|
```
|
|
84
110
|
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
### Templates
|
|
88
|
-
|
|
89
|
-
Templates are plain HTML strings - runtime-agnostic, easy to test, easy to move between files:
|
|
90
|
-
|
|
91
|
-
```js
|
|
92
|
-
// Separate file: my-component.template.js
|
|
93
|
-
import { html } from '@symbiotejs/symbiote';
|
|
94
|
-
|
|
95
|
-
export default html`
|
|
96
|
-
<h1>{{title}}</h1>
|
|
97
|
-
<button ${{onclick: 'doSomething'}}>Go</button>
|
|
98
|
-
`;
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
The `html` function supports two interpolation modes:
|
|
102
|
-
- **Object** → reactive binding: `${{onclick: 'handler'}}`
|
|
103
|
-
- **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.
|
|
104
112
|
|
|
105
113
|
### Itemize (dynamic reactive lists)
|
|
106
114
|
|
|
@@ -124,7 +132,7 @@ TaskList.template = html`
|
|
|
124
132
|
|
|
125
133
|
### Pop-up binding (`^`)
|
|
126
134
|
|
|
127
|
-
|
|
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$()`):
|
|
128
136
|
|
|
129
137
|
```html
|
|
130
138
|
<!-- Text binding to parent property: -->
|
|
@@ -134,9 +142,10 @@ The `^` prefix works in any nested component template - it walks up the DOM tree
|
|
|
134
142
|
<button ${{onclick: '^parentHandler'}}>Click</button>
|
|
135
143
|
```
|
|
136
144
|
|
|
137
|
-
###
|
|
145
|
+
### Namespace bindings and named contexts
|
|
146
|
+
|
|
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:
|
|
138
148
|
|
|
139
|
-
Share state across components without prop drilling:
|
|
140
149
|
```js
|
|
141
150
|
import { PubSub, html } from '@symbiotejs/symbiote';
|
|
142
151
|
|
|
@@ -154,7 +163,7 @@ let template = html`<h2>{{APP/user}}</h2>`;
|
|
|
154
163
|
|
|
155
164
|
### Shared context (`*`)
|
|
156
165
|
|
|
157
|
-
|
|
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:
|
|
158
167
|
|
|
159
168
|
```html
|
|
160
169
|
<upload-btn ctx="gallery"></upload-btn>
|
|
@@ -180,7 +189,7 @@ class StatusBar extends Symbiote {
|
|
|
180
189
|
}
|
|
181
190
|
```
|
|
182
191
|
|
|
183
|
-
All three components access the same `*files` state
|
|
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.
|
|
184
193
|
|
|
185
194
|
### Application routing
|
|
186
195
|
|
|
@@ -195,11 +204,11 @@ AppRouter.initRoutingCtx('R', {
|
|
|
195
204
|
});
|
|
196
205
|
```
|
|
197
206
|
|
|
198
|
-
### CSS
|
|
207
|
+
### CSS styling
|
|
199
208
|
|
|
200
|
-
Shadow DOM is
|
|
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.
|
|
201
210
|
|
|
202
|
-
|
|
211
|
+
Light DOM components use regular CSS:
|
|
203
212
|
|
|
204
213
|
```js
|
|
205
214
|
MyComponent.rootStyles = css`
|
|
@@ -212,9 +221,9 @@ MyComponent.rootStyles = css`
|
|
|
212
221
|
`;
|
|
213
222
|
```
|
|
214
223
|
|
|
215
|
-
|
|
224
|
+
Symbiote.js applies this style to the nearest containing shadow root, when one exists, or to the document.
|
|
216
225
|
|
|
217
|
-
|
|
226
|
+
Use Shadow DOM for opt-in isolation:
|
|
218
227
|
|
|
219
228
|
```js
|
|
220
229
|
class Isolated extends Symbiote {}
|
|
@@ -225,9 +234,9 @@ Isolated.shadowStyles = css`
|
|
|
225
234
|
`;
|
|
226
235
|
```
|
|
227
236
|
|
|
228
|
-
|
|
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.
|
|
229
238
|
|
|
230
|
-
### CSS
|
|
239
|
+
### CSS data
|
|
231
240
|
|
|
232
241
|
Components can read CSS custom property values to initiate reactive state:
|
|
233
242
|
|
|
@@ -247,21 +256,21 @@ MyWidget.template = html`
|
|
|
247
256
|
|
|
248
257
|
## Best for
|
|
249
258
|
|
|
250
|
-
-
|
|
251
|
-
-
|
|
252
|
-
-
|
|
253
|
-
-
|
|
254
|
-
-
|
|
255
|
-
-
|
|
256
|
-
-
|
|
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
|
|
257
266
|
|
|
258
|
-
## Docs
|
|
267
|
+
## Docs and examples
|
|
259
268
|
|
|
260
269
|
- [Documentation](https://github.com/symbiotejs/symbiote.js/blob/main/docs/README.md)
|
|
261
|
-
- [Live
|
|
262
|
-
- [JSDA-Kit](https://github.com/rnd-pro/jsda-kit)
|
|
263
|
-
- [AI / llms.txt](https://rnd-pro.com/symbiote/llms.txt)
|
|
264
|
-
- [Full docs (single file)](https://rnd-pro.com/symbiote/llms-full.txt)
|
|
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
|
|
265
274
|
|
|
266
275
|
## Related articles
|
|
267
276
|
|
|
@@ -270,11 +279,11 @@ MyWidget.template = html`
|
|
|
270
279
|
- [Symbiote.js vs Lit](https://dev.to/foxeyes/lit-vs-symbiotejs-22gj)
|
|
271
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)
|
|
272
281
|
|
|
273
|
-
|
|
282
|
+
Questions and proposals are welcome in [Symbiote Discussions](https://github.com/symbiotejs/symbiote.js/discussions).
|
|
274
283
|
|
|
275
284
|
---
|
|
276
285
|
|
|
277
|
-
© [rnd-pro.com](https://rnd-pro.com)
|
|
286
|
+
© [rnd-pro.com](https://rnd-pro.com), MIT License
|
|
278
287
|
|
|
279
288
|
---
|
|
280
289
|
|
|
@@ -5396,6 +5405,25 @@ class UserCard extends Symbiote {
|
|
|
5396
5405
|
|
|
5397
5406
|
The returned text is appended to each component-owned tool description.
|
|
5398
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
|
+
|
|
5399
5427
|
## Notes
|
|
5400
5428
|
|
|
5401
5429
|
- This is an experimental release. Names, metadata shape, and browser APIs may change.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"type": "module",
|
|
3
3
|
"name": "@symbiotejs/symbiote",
|
|
4
|
-
"version": "3.8.
|
|
4
|
+
"version": "3.8.3",
|
|
5
5
|
"description": "Symbiote.js - zero-dependency close-to-platform frontend library to build super-powered web components",
|
|
6
6
|
"author": "team@rnd-pro.com",
|
|
7
7
|
"license": "MIT",
|
|
@@ -11,10 +11,11 @@
|
|
|
11
11
|
"prepublishOnly": "npm test",
|
|
12
12
|
"build:llms": "node scripts/build-llms.js",
|
|
13
13
|
"pub": "npm test && npm run types && npm run build:llms && npm publish",
|
|
14
|
+
"test:setup": "playwright install chromium && puppeteer browsers install chrome",
|
|
14
15
|
"test:unit": "node --test test/node/*.test.js",
|
|
15
|
-
"test:browser": "
|
|
16
|
+
"test:browser": "playwright test",
|
|
16
17
|
"test:webmcp:native": "node --test test/browser/webmcp.native.test.js",
|
|
17
|
-
"test": "node --test test/node/*.test.js &&
|
|
18
|
+
"test": "node --test test/node/*.test.js && playwright test && npm run test:webmcp:native"
|
|
18
19
|
},
|
|
19
20
|
"files": [
|
|
20
21
|
"core/*",
|
package/types/core/webmcp.d.ts
CHANGED
|
@@ -6,6 +6,7 @@ export function registerWebMCPTool(owner: any, key: string, descriptor: ToolDesc
|
|
|
6
6
|
export function syncWebMCPTools(owner: any): void;
|
|
7
7
|
export function unregisterWebMCPTools(owner: any): void;
|
|
8
8
|
export function getActiveWebMCPTools(): WebMCPRegistryEntry[];
|
|
9
|
+
export function executeWebMCPTool(name: string, input?: any): any | Promise<any>;
|
|
9
10
|
export function installWebMCP(SymbioteClass?: typeof Symbiote): void;
|
|
10
11
|
export class ToolDescriptor {
|
|
11
12
|
constructor(options?: ToolDescriptorOptions);
|
|
@@ -28,6 +29,7 @@ declare namespace _default {
|
|
|
28
29
|
export { unregisterWebMCPTools };
|
|
29
30
|
export { syncWebMCPTools };
|
|
30
31
|
export { getActiveWebMCPTools };
|
|
32
|
+
export { executeWebMCPTool };
|
|
31
33
|
}
|
|
32
34
|
export default _default;
|
|
33
35
|
export type WebMCPToolResultText = {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"webmcp.d.ts","sourceRoot":"","sources":["../../core/webmcp.js"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"webmcp.d.ts","sourceRoot":"","sources":["../../core/webmcp.js"],"names":[],"mappings":"AAgqBA,0CALW,GAAG,OACH,MAAM,cACN,cAAc,GACZ,CAAC,mBAAmB,GAAG;IAAC,UAAU,EAAE,eAAe,GAAG,IAAI,CAAA;CAAC,CAAC,GAAG,OAAO,CAAC,mBAAmB,GAAG;IAAC,UAAU,EAAE,eAAe,GAAG,IAAI,CAAA;CAAC,CAAC,CAqC9I;AA2CD,uCADY,GAAG,QA6Bd;AAGD,6CADY,GAAG,QAyBd;AAGD,wCADc,mBAAmB,EAAE,CAIlC;AASD,wCAJW,MAAM,gBAEJ,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAK9B;AAGD,8CADY,OAAO,QAAQ,QA+B1B;AAzOD;IAKE,sBADY,qBAAqB,EAWhC;IARC,aAAwB;IACxB,gCAlmB6B,GAAG,KAAK,MAAM,EAkmBsB;IACjE,iBAAuD;IAEvD,eAlmBmB,GAAG,KAAK,OAAO,CAkmBV;IACxB,eAA8B;IAC9B,oBAAkC;IAClC,iBAAsC;IASxC,4BAJW,GAAG,UACH,KAAK,GACH,GAAG,CAOf;;CACF;AAED,yCAUK;;;;;;;;;;;;;UAhpBS,MAAM;UACN,MAAM;;;cAKN,oBAAoB,EAAE;cACtB,OAAO;;;WAKP,MAAM;kBACN,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,MAAM,CAAC;kBAClC,MAAS,CAAC,CAAC,KAAK,CAAC,EAAE,GAAG,QAAW,CAAC;cAClC,CAAC,IAAI,CAAC,KAAQ,EAAE,KAAK,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,KAAK,KAAK,GAAG;WAClD,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO;WACxB,MAAM,EAAE;gBACR,MAAM,EAAE;;;;UAMR,MAAM;SACN,MAAM;aACN,MAAM;eACN,WAAW,GAAG,SAAS;eACvB,MAAM;0BACN,MAAM;iBACN,MAAM;;YAEN,OAAO;kBACP,OAAO;;qBAxCA,eAAe;mBADjB,aAAa"}
|