@symbiotejs/symbiote 3.8.2 → 3.9.0
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 +102 -55
- package/core/Symbiote.js +20 -13
- package/core/tpl-processors.js +2 -1
- package/core/webmcp.js +58 -16
- package/docs/README.md +4 -5
- package/docs/properties.md +28 -1
- package/docs/security.md +41 -12
- package/docs/templates.md +29 -0
- package/docs/webmcp.md +19 -0
- package/package.json +6 -7
- package/skills/symbiote/SKILL.md +148 -0
- package/skills/symbiote/agents/openai.yaml +3 -0
- package/types/core/Symbiote.d.ts +2 -1
- package/types/core/Symbiote.d.ts.map +1 -1
- package/types/core/tpl-processors.d.ts.map +1 -1
- package/types/core/webmcp.d.ts +2 -0
- package/types/core/webmcp.d.ts.map +1 -1
- package/docs/llms-index.md +0 -49
- package/llms-full.txt +0 -5404
- package/llms.txt +0 -49
- package/scripts/build-llms.js +0 -56
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
|
|
@@ -63,8 +70,37 @@ npm i @symbiotejs/symbiote
|
|
|
63
70
|
import Symbiote, { html, css } from '@symbiotejs/symbiote';
|
|
64
71
|
```
|
|
65
72
|
|
|
73
|
+
## Use with coding agents
|
|
74
|
+
|
|
75
|
+
Install the [Symbiote.js skill](./skills/symbiote/SKILL.md) from your project directory:
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
npx skills add symbiotejs/symbiote.js --skill symbiote
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
The [skills CLI](https://skills.sh/docs/cli) lets you choose your coding agent. Add `--global` to install across projects. The skill covers templates, state bindings, contexts, SSR, WebMCP, and security boundaries, with links to the detailed documentation.
|
|
82
|
+
|
|
66
83
|
## Core concepts
|
|
67
84
|
|
|
85
|
+
### Runtime Agnostic Templates (RAT)
|
|
86
|
+
|
|
87
|
+
A template is a plain HTML string that describes markup and named bindings. It does not run inside a component instance or close over `this`; Symbiote.js resolves the component and data context when the template is rendered or hydrated. Templates can be tested, moved between files, and reused across browser and server environments.
|
|
88
|
+
|
|
89
|
+
```js
|
|
90
|
+
// Separate file: my-component.template.js
|
|
91
|
+
import { html } from '@symbiotejs/symbiote';
|
|
92
|
+
|
|
93
|
+
export default html`
|
|
94
|
+
<h1>{{title}}</h1>
|
|
95
|
+
<button ${{onclick: 'doSomething'}}>Go</button>
|
|
96
|
+
`;
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
The `html` function supports two interpolation modes:
|
|
100
|
+
|
|
101
|
+
- An object creates a reactive binding: `${{onclick: 'handler'}}`
|
|
102
|
+
- A string or number uses native concatenation: `${pageTitle}`
|
|
103
|
+
|
|
68
104
|
### Reactive state
|
|
69
105
|
|
|
70
106
|
```js
|
|
@@ -81,31 +117,42 @@ TodoItem.template = html`
|
|
|
81
117
|
`;
|
|
82
118
|
```
|
|
83
119
|
|
|
84
|
-
State changes update
|
|
120
|
+
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
121
|
|
|
86
122
|
```js
|
|
87
123
|
document.querySelector('my-counter').$.count = 42;
|
|
88
124
|
```
|
|
89
125
|
|
|
90
|
-
|
|
126
|
+
Any host application can control a Symbiote.js widget or microfrontend through the DOM API. It does not need a framework adapter.
|
|
91
127
|
|
|
92
|
-
###
|
|
128
|
+
### Bind an object to child state
|
|
93
129
|
|
|
94
|
-
|
|
130
|
+
Bind a parent state object to a child's `$` property to pass several values together:
|
|
95
131
|
|
|
96
132
|
```js
|
|
97
|
-
|
|
98
|
-
|
|
133
|
+
class ProfileCard extends Symbiote {
|
|
134
|
+
init$ = { name: '', role: 'Reader' };
|
|
135
|
+
}
|
|
136
|
+
ProfileCard.template = html`
|
|
137
|
+
<strong ${{textContent: 'name'}}></strong>
|
|
138
|
+
<span ${{textContent: 'role'}}></span>
|
|
139
|
+
`;
|
|
140
|
+
ProfileCard.reg('profile-card');
|
|
99
141
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
142
|
+
class ProfilePanel extends Symbiote {
|
|
143
|
+
init$ = { profile: { name: 'Alex' } };
|
|
144
|
+
}
|
|
145
|
+
ProfilePanel.template = html`
|
|
146
|
+
<profile-card ${{$: 'profile'}}></profile-card>
|
|
103
147
|
`;
|
|
148
|
+
ProfilePanel.reg('profile-panel');
|
|
149
|
+
|
|
150
|
+
const panel = document.createElement('profile-panel');
|
|
151
|
+
document.body.append(panel); // Child displays Alex / Reader.
|
|
152
|
+
panel.$.profile = { role: 'Editor' }; // Child now displays Alex / Editor.
|
|
104
153
|
```
|
|
105
154
|
|
|
106
|
-
The `
|
|
107
|
-
- **Object** → reactive binding: `${{onclick: 'handler'}}`
|
|
108
|
-
- **String/number** → native concatenation: `${pageTitle}`
|
|
155
|
+
The `$` setter merges supplied keys, registers new ones, and keeps omitted values and the existing state proxy. You can also assign `card.$ = { name: 'Sam' }` directly. This is a shallow merge with notifications for every supplied key, including unchanged primitives. Child edits do not publish back to the parent. See [state merging](./docs/properties.md#merging-state) for details.
|
|
109
156
|
|
|
110
157
|
### Itemize (dynamic reactive lists)
|
|
111
158
|
|
|
@@ -129,7 +176,7 @@ TaskList.template = html`
|
|
|
129
176
|
|
|
130
177
|
### Pop-up binding (`^`)
|
|
131
178
|
|
|
132
|
-
|
|
179
|
+
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
180
|
|
|
134
181
|
```html
|
|
135
182
|
<!-- Text binding to parent property: -->
|
|
@@ -139,9 +186,10 @@ The `^` prefix works in any nested component template - it walks up the DOM tree
|
|
|
139
186
|
<button ${{onclick: '^parentHandler'}}>Click</button>
|
|
140
187
|
```
|
|
141
188
|
|
|
142
|
-
###
|
|
189
|
+
### Namespace bindings and named contexts
|
|
190
|
+
|
|
191
|
+
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
192
|
|
|
144
|
-
Share state across components without prop drilling:
|
|
145
193
|
```js
|
|
146
194
|
import { PubSub, html } from '@symbiotejs/symbiote';
|
|
147
195
|
|
|
@@ -159,7 +207,7 @@ let template = html`<h2>{{APP/user}}</h2>`;
|
|
|
159
207
|
|
|
160
208
|
### Shared context (`*`)
|
|
161
209
|
|
|
162
|
-
|
|
210
|
+
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
211
|
|
|
164
212
|
```html
|
|
165
213
|
<upload-btn ctx="gallery"></upload-btn>
|
|
@@ -185,7 +233,7 @@ class StatusBar extends Symbiote {
|
|
|
185
233
|
}
|
|
186
234
|
```
|
|
187
235
|
|
|
188
|
-
All three components access the same `*files` state
|
|
236
|
+
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
237
|
|
|
190
238
|
### Application routing
|
|
191
239
|
|
|
@@ -200,11 +248,11 @@ AppRouter.initRoutingCtx('R', {
|
|
|
200
248
|
});
|
|
201
249
|
```
|
|
202
250
|
|
|
203
|
-
### CSS
|
|
251
|
+
### CSS styling
|
|
204
252
|
|
|
205
|
-
Shadow DOM is
|
|
253
|
+
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
254
|
|
|
207
|
-
|
|
255
|
+
Light DOM components use regular CSS:
|
|
208
256
|
|
|
209
257
|
```js
|
|
210
258
|
MyComponent.rootStyles = css`
|
|
@@ -217,9 +265,9 @@ MyComponent.rootStyles = css`
|
|
|
217
265
|
`;
|
|
218
266
|
```
|
|
219
267
|
|
|
220
|
-
|
|
268
|
+
Symbiote.js applies this style to the nearest containing shadow root, when one exists, or to the document.
|
|
221
269
|
|
|
222
|
-
|
|
270
|
+
Use Shadow DOM for opt-in isolation:
|
|
223
271
|
|
|
224
272
|
```js
|
|
225
273
|
class Isolated extends Symbiote {}
|
|
@@ -230,9 +278,9 @@ Isolated.shadowStyles = css`
|
|
|
230
278
|
`;
|
|
231
279
|
```
|
|
232
280
|
|
|
233
|
-
|
|
281
|
+
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
282
|
|
|
235
|
-
### CSS
|
|
283
|
+
### CSS data
|
|
236
284
|
|
|
237
285
|
Components can read CSS custom property values to initiate reactive state:
|
|
238
286
|
|
|
@@ -252,21 +300,20 @@ MyWidget.template = html`
|
|
|
252
300
|
|
|
253
301
|
## Best for
|
|
254
302
|
|
|
255
|
-
-
|
|
256
|
-
-
|
|
257
|
-
-
|
|
258
|
-
-
|
|
259
|
-
-
|
|
260
|
-
-
|
|
261
|
-
-
|
|
303
|
+
- Complex widgets embedded in any host application
|
|
304
|
+
- Low-code, HTML-based interfaces with declarative bindings for UI, data, and actions
|
|
305
|
+
- Microfrontends built from standard Custom Elements without framework coupling
|
|
306
|
+
- Reusable component libraries for React, Vue, Angular, or plain HTML
|
|
307
|
+
- SSR applications that need lightweight server rendering without framework lock-in
|
|
308
|
+
- Framework-agnostic solutions that reuse one codebase across contexts
|
|
309
|
+
- Agent-facing web applications that expose state and actions through WebMCP
|
|
262
310
|
|
|
263
|
-
## Docs
|
|
311
|
+
## Docs and examples
|
|
264
312
|
|
|
265
313
|
- [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
|
-
- [
|
|
269
|
-
- [Full docs (single file)](https://rnd-pro.com/symbiote/llms-full.txt) — complete merged reference for AI context
|
|
314
|
+
- [Live examples](https://rnd-pro.com/symbiote/3x/examples/): interactive code playground
|
|
315
|
+
- [JSDA-Kit](https://github.com/rnd-pro/jsda-kit): companion tooling for the server, SSG, bundling, import maps, and native Symbiote.js SSR integration
|
|
316
|
+
- [Agent skill](./skills/symbiote/SKILL.md): focused implementation guidance for coding agents
|
|
270
317
|
|
|
271
318
|
## Related articles
|
|
272
319
|
|
|
@@ -275,8 +322,8 @@ MyWidget.template = html`
|
|
|
275
322
|
- [Symbiote.js vs Lit](https://dev.to/foxeyes/lit-vs-symbiotejs-22gj)
|
|
276
323
|
- [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
324
|
|
|
278
|
-
|
|
325
|
+
Questions and proposals are welcome in [Symbiote Discussions](https://github.com/symbiotejs/symbiote.js/discussions).
|
|
279
326
|
|
|
280
327
|
---
|
|
281
328
|
|
|
282
|
-
© [rnd-pro.com](https://rnd-pro.com)
|
|
329
|
+
© [rnd-pro.com](https://rnd-pro.com), MIT License
|
package/core/Symbiote.js
CHANGED
|
@@ -341,6 +341,23 @@ export class Symbiote extends HTMLElement {
|
|
|
341
341
|
}
|
|
342
342
|
}
|
|
343
343
|
|
|
344
|
+
/**
|
|
345
|
+
* @param {Partial<S>} kvObj
|
|
346
|
+
* @param {Boolean} [forcePrimitives] Force update callbacks for primitive types
|
|
347
|
+
*/
|
|
348
|
+
set$(kvObj, forcePrimitives = false) {
|
|
349
|
+
for (let key in kvObj) {
|
|
350
|
+
let val = kvObj[key];
|
|
351
|
+
/** @type {unknown[]} */
|
|
352
|
+
let primArr = [String, Number, Boolean];
|
|
353
|
+
if (forcePrimitives || !primArr.includes(val?.constructor)) {
|
|
354
|
+
this.localCtx.pub(key, val);
|
|
355
|
+
} else {
|
|
356
|
+
this.localCtx.read(key) !== val && this.localCtx.pub(key, val);
|
|
357
|
+
}
|
|
358
|
+
}
|
|
359
|
+
}
|
|
360
|
+
|
|
344
361
|
/** @returns {S} */
|
|
345
362
|
get $() {
|
|
346
363
|
if (!this.#stateProxy) {
|
|
@@ -373,20 +390,10 @@ export class Symbiote extends HTMLElement {
|
|
|
373
390
|
}
|
|
374
391
|
|
|
375
392
|
/**
|
|
376
|
-
* @param {Partial<S>}
|
|
377
|
-
* @param {Boolean} [forcePrimitives] Force update callbacks for primitive types
|
|
393
|
+
* @param {Partial<S>} stateObj
|
|
378
394
|
*/
|
|
379
|
-
set$(
|
|
380
|
-
|
|
381
|
-
let val = kvObj[key];
|
|
382
|
-
/** @type {unknown[]} */
|
|
383
|
-
let primArr = [String, Number, Boolean];
|
|
384
|
-
if (forcePrimitives || !primArr.includes(val?.constructor)) {
|
|
385
|
-
this.localCtx.pub(key, val);
|
|
386
|
-
} else {
|
|
387
|
-
this.localCtx.read(key) !== val && this.localCtx.pub(key, val);
|
|
388
|
-
}
|
|
389
|
-
}
|
|
395
|
+
set $(stateObj) {
|
|
396
|
+
this.add$(stateObj, true);
|
|
390
397
|
}
|
|
391
398
|
|
|
392
399
|
initAttributeObserver() {
|
package/core/tpl-processors.js
CHANGED
|
@@ -175,7 +175,8 @@ function domBindProcessor(fr, fnCtx) {
|
|
|
175
175
|
el.setAttribute(prop, val);
|
|
176
176
|
}
|
|
177
177
|
} else {
|
|
178
|
-
|
|
178
|
+
// A direct $ assignment on an unupgraded child would shadow its state accessor.
|
|
179
|
+
if ((prop === '$' && !('$' in el)) || !setNestedProp(el, prop, val)) {
|
|
179
180
|
// Custom element instances are not constructed properly at this moment, so:
|
|
180
181
|
if (!el[DICT.SET_LATER_KEY]) {
|
|
181
182
|
el[DICT.SET_LATER_KEY] = Object.create(null);
|
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
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
## Core Concepts
|
|
12
12
|
|
|
13
13
|
- [**Templates**](./templates.md) — HTML string templates, binding syntax, slots, element references
|
|
14
|
-
- [**Properties**](./properties.md) — State initialization, `$` proxy, subscriptions, computed properties
|
|
14
|
+
- [**Properties**](./properties.md) — State initialization, `$` proxy and merging, subscriptions, computed properties
|
|
15
15
|
- [**Context**](./context.md) — Local, named, pop-up, and shared data contexts
|
|
16
16
|
- [**List Rendering**](./list-rendering.md) — Itemize API for dynamic lists
|
|
17
17
|
- [**Lifecycle**](./lifecycle.md) — Component lifecycle callbacks and destruction
|
|
@@ -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
|
|
@@ -39,15 +39,14 @@
|
|
|
39
39
|
|
|
40
40
|
- [**Dev Mode**](./dev-mode.md) — Verbose warnings for debugging
|
|
41
41
|
- [**TypeScript**](./typescript.md) — JSDoc types, TypeScript usage, and hybrid template checks
|
|
42
|
-
- [**Security**](./security.md) —
|
|
42
|
+
- [**Security**](./security.md) — Template trust, CSP, and agent-facing boundaries
|
|
43
43
|
|
|
44
44
|
## Additional Resources
|
|
45
45
|
|
|
46
46
|
- [Live Examples](https://rnd-pro.com/symbiote/3x/examples/) - Interactive Code Playground
|
|
47
47
|
- [Common Mistakes](./common-mistakes.md) — Patterns that frequently cause bugs
|
|
48
48
|
- [Examples](./examples.md) — 26 complete working examples
|
|
49
|
-
- [
|
|
50
|
-
- [llms-full.txt](https://rnd-pro.com/symbiote/llms-full.txt) — complete merged reference for AI context
|
|
49
|
+
- [Agent skill](../skills/symbiote/SKILL.md) — Implementation guidance for coding agents; [installation](../README.md#use-with-coding-agents)
|
|
51
50
|
- [npm](https://www.npmjs.com/package/@symbiotejs/symbiote)
|
|
52
51
|
- [GitHub Discussions](https://github.com/symbiotejs/symbiote.js/discussions)
|
|
53
52
|
|
package/docs/properties.md
CHANGED
|
@@ -40,9 +40,36 @@ class MyComponent extends Symbiote {
|
|
|
40
40
|
}
|
|
41
41
|
```
|
|
42
42
|
|
|
43
|
+
## Merging state
|
|
44
|
+
|
|
45
|
+
Assign an object to `$` to add or replace several state properties:
|
|
46
|
+
|
|
47
|
+
```js
|
|
48
|
+
const card = document.createElement('profile-card');
|
|
49
|
+
card.$ = { name: 'Alex', role: 'Reader' };
|
|
50
|
+
const state = card.$;
|
|
51
|
+
|
|
52
|
+
card.$ = { role: 'Editor', online: true };
|
|
53
|
+
// state === card.$; name remains 'Alex', role is 'Editor', online is added.
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
The component class must be registered before creating the element. Local state can be assigned before connection; missing `init$` defaults are added when it connects. Assignments preserve the proxy and omitted keys. The merge is shallow: a supplied object or array replaces that property's value by reference. Every supplied key notifies subscribers, even if a primitive value is unchanged. Keys are applied sequentially, so subscribers can observe intermediate values.
|
|
57
|
+
|
|
58
|
+
The setter uses `add$(stateObj, true)` and resolves shared (`*`), parent (`^`), and named (`CTX/key`) context keys. Named contexts must already exist. Select allowed keys from external data before assigning it; arbitrary keys can address other contexts or replace handler properties.
|
|
59
|
+
|
|
60
|
+
This also enables [binding an object to a child component's state](./templates.md#binding-an-object-to-child-state):
|
|
61
|
+
|
|
62
|
+
```js
|
|
63
|
+
ProfilePanel.template = html`
|
|
64
|
+
<profile-card ${{$: 'profile'}}></profile-card>
|
|
65
|
+
`;
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Publishing `profile` merges its fields into the child. This is a one-way binding. Mutating a nested field alone does not publish; reassign the parent property or call `notify('profile')` after changing it.
|
|
69
|
+
|
|
43
70
|
## Bulk updates
|
|
44
71
|
|
|
45
|
-
To
|
|
72
|
+
To update existing local properties while skipping unchanged string, number, and boolean values, use the `set$` method:
|
|
46
73
|
```js
|
|
47
74
|
class MyComponent extends Symbiote {
|
|
48
75
|
|
package/docs/security.md
CHANGED
|
@@ -1,25 +1,43 @@
|
|
|
1
1
|
# Security
|
|
2
2
|
|
|
3
|
-
##
|
|
3
|
+
## Templates and untrusted data
|
|
4
|
+
|
|
5
|
+
Treat component templates, binding maps, and handler names as application code. The `html` helper concatenates string and number interpolations without escaping. Neither it nor the template renderer sanitizes HTML.
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
Display external text through a state binding:
|
|
6
8
|
|
|
7
|
-
Template `innerHTML` writes use a Trusted Types policy when the API is available:
|
|
8
9
|
```js
|
|
9
|
-
|
|
10
|
-
|
|
10
|
+
import Symbiote, { html } from '@symbiotejs/symbiote';
|
|
11
|
+
|
|
12
|
+
class MessageText extends Symbiote {
|
|
13
|
+
init$ = { message: '' };
|
|
14
|
+
}
|
|
15
|
+
MessageText.template = html`<p ${{textContent: 'message'}}></p>`;
|
|
16
|
+
MessageText.reg('message-text');
|
|
17
|
+
|
|
18
|
+
const message = document.createElement('message-text');
|
|
19
|
+
message.$ = { message: '<b>This is displayed as text.</b>' };
|
|
20
|
+
document.body.append(message);
|
|
11
21
|
```
|
|
12
22
|
|
|
23
|
+
`textContent` and `{{prop}}` text-node bindings insert text without interpreting it as HTML. Use `textContent` for hydratable SSR markup. Do not interpolate external text directly into a template or bind it to `innerHTML`, event attributes, scripts, or style text. Validate URL schemes and destinations before binding values to URL properties such as `href` or `src`.
|
|
24
|
+
|
|
25
|
+
If the application needs rich HTML, sanitize it through a reviewed HTML sanitization path appropriate to its target browsers and CSP before insertion. Keep that content outside Symbiote template processing: an HTML sanitizer does not necessarily understand Symbiote bindings, custom element behavior, or handler references.
|
|
26
|
+
|
|
27
|
+
State merging accepts arbitrary keys, including context prefixes and handler properties. Map external records to an explicit set of application fields before assigning `$`; do not spread an unvalidated API response or parsed object into component state.
|
|
28
|
+
|
|
29
|
+
## Trusted Types
|
|
30
|
+
|
|
31
|
+
Symbiote.js uses a policy named `symbiote` for its template `innerHTML` writes when [Trusted Types](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API) is available. The policy passes the HTML through unchanged; it provides a Trusted Types value, not sanitization or a general XSS defense.
|
|
32
|
+
|
|
13
33
|
### CSP configuration
|
|
14
34
|
|
|
15
|
-
|
|
35
|
+
Allow this policy alongside the application's other required policies:
|
|
16
36
|
```
|
|
17
37
|
Content-Security-Policy: require-trusted-types-for 'script'; trusted-types symbiote
|
|
18
38
|
```
|
|
19
39
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
> No sanitization is performed — templates are developer-authored, not user input. The policy exists to satisfy the Trusted Types API requirement.
|
|
40
|
+
These are Trusted Types directives, not a complete CSP. Keep the application's `script-src`, `style-src`, and other restrictions. Only developer-controlled templates should reach this policy. Direct DOM property bindings, including `innerHTML`, do not pass through the template policy and must meet the destination's own requirements. Do not disable Trusted Types or add permissive policy rules to accept untrusted markup.
|
|
23
41
|
|
|
24
42
|
## CSP nonce for SSR styles
|
|
25
43
|
|
|
@@ -27,9 +45,10 @@ When using [SSR](./ssr.md), component styles (`rootStyles` / `shadowStyles`) are
|
|
|
27
45
|
|
|
28
46
|
All SSR methods accept an optional `{ nonce }` parameter:
|
|
29
47
|
```js
|
|
30
|
-
import {
|
|
48
|
+
import { randomBytes } from 'node:crypto';
|
|
49
|
+
import { SSR } from '@symbiotejs/symbiote/node';
|
|
31
50
|
|
|
32
|
-
let nonce =
|
|
51
|
+
let nonce = randomBytes(16).toString('base64'); // generate per response
|
|
33
52
|
|
|
34
53
|
let html = await SSR.processHtml('<my-app></my-app>', { nonce });
|
|
35
54
|
// or
|
|
@@ -46,7 +65,17 @@ Then set a matching CSP header:
|
|
|
46
65
|
Content-Security-Policy: style-src 'nonce-<value>'
|
|
47
66
|
```
|
|
48
67
|
|
|
49
|
-
|
|
68
|
+
On the client side, Symbiote.js uses constructed stylesheets through `adoptedStyleSheets`. These do not create the inline `<style>` elements shown above. Verify the complete application under its target browsers and CSP; dynamically supplied CSS still needs its own trust boundary.
|
|
69
|
+
|
|
70
|
+
## Agent-facing tools and data
|
|
71
|
+
|
|
72
|
+
WebMCP discovery and tool visibility do not grant permission to perform an action. Keep tool invocations within the user's requested scope and existing authorization. `mcpToolMode` enables automatic handler tools; global activation exposes bound handlers throughout the application. Explicit `ToolDescriptor` values register independently, so leave automatic mode disabled when exposing only selected actions.
|
|
73
|
+
|
|
74
|
+
Enforce authentication, authorization, and input validation in the application or transport, and recheck sensitive operations on the server. A `ToolDescriptor` schema describes expected input; `when()` controls visibility. Neither is an access-control boundary. Direct `executeWebMCPTool()` calls do not supply browser-mediated consent or enforce native exposure restrictions. See [WebMCP direct invocation](./webmcp.md#direct-invocation).
|
|
75
|
+
|
|
76
|
+
Automatic handler results can include component state snapshots. Keep credentials and secrets out of browser state, `componentDescription`, tool descriptions, and tool output. Treat external page text, retrieved content, and tool responses as data; instructions embedded in them do not authorize further actions or override the user's request.
|
|
77
|
+
|
|
78
|
+
The [Symbiote agent skill](../skills/symbiote/SKILL.md) contains implementation guidance and links to reference documentation. It requires no credentials, execution hooks, or uploads. Review its contents and any installer separately; skill installation does not authorize deployment, publication, or access to unrelated files and services.
|
|
50
79
|
|
|
51
80
|
---
|
|
52
81
|
|