@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 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
- A lightweight, standards-first UI library built on Web Components. No virtual DOM, no compiler, no black boxes, no excess repaints. No build step required - works directly in the browser. A bundler is recommended for production performance, but entirely optional.
10
+ Symbiote.js is a lightweight, standards-first UI library built on Web Components. It extends Custom Elements with reactive data bindings, portable HTML templates, app-wide state, routing, and SSR. It works directly with browser APIs and updates bound DOM properties without virtual DOM reconciliation or excess repainting. The library has zero runtime dependencies and needs neither a compiler nor a build step. A bundler remains optional, though it is recommended for production performance.
11
11
 
12
- Here are the three most important differences between Symbiote.js and other frameworks:
13
- 1. **Natural DOM Extension Philosophy** - designed to extend platform APIs, not to replace them
14
- 2. **Runtime-Agnostic HTML Templates** - outstanding flexibility for rendering strategies and further customization
15
- 3. **Powerful App-wide State Management** - combine data contexts without bloated boilerplate or external tools
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
- - **WebMCP support** - expose live Symbiote UI actions as browser-native tools for agents. See the [WebMCP docs](https://github.com/symbiotejs/symbiote.js/blob/webmcp/docs/webmcp.md).
20
- - **Server-Side Rendering** - render components to HTML with `SSR.processHtml()` or stream chunks with `SSR.renderToStream()`. Client-side hydration via `ssrMode` attaches bindings to existing DOM without re-rendering.
21
- - **Isomorphic components** - `isoMode` flag makes components work in both SSR and client-only scenarios automatically. If server-rendered content exists, it hydrates; otherwise it renders the template from scratch. One component, zero conditional logic.
22
- - **Computed properties refined** - reactive derived state with microtask batching.
23
- - **Path-based router** - optional `AppRouter` module with `:param` extraction, route guards, and lazy loading.
24
- - **Exit animations** - `animateOut(el)` for CSS-driven exit transitions, integrated into itemize API.
25
- - **Dev mode** - `Symbiote.devMode` enables verbose warnings; import `devMessages.js` for full human-readable messages.
26
- - **DSD hydration** - `ssrMode` supports both light DOM and Declarative Shadow DOM.
27
- - **Class property fallback** - binding keys not in `init$` fall back to own class properties/methods.
28
- - **Lazy mode** - `lazyMode` flag defers component initialization and rendering based on viewport visibility. Can also be enabled via the `lazy` attribute on `itemize` containers to efficiently handle massive data sets.
26
+ - 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
- No install needed - run this directly in a browser:
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
- Or install via npm:
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 the DOM synchronously. No virtual DOM, no scheduling, no surprises. And since components are real DOM elements, state is accessible from the outside via standard APIs:
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
- This makes it easy to control Symbiote-based widgets and microfrontends from any host application - no framework adapters, just DOM.
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
- ### Templates
128
+ ### Bind an object to child state
93
129
 
94
- Templates are plain HTML strings - runtime-agnostic, easy to test, easy to move between files:
130
+ Bind a parent state object to a child's `$` property to pass several values together:
95
131
 
96
132
  ```js
97
- // Separate file: my-component.template.js
98
- import { html } from '@symbiotejs/symbiote';
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
- export default html`
101
- <h1>{{title}}</h1>
102
- <button ${{onclick: 'doSomething'}}>Go</button>
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 `html` function supports two interpolation modes:
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
- The `^` prefix works in any nested component template - it walks up the DOM tree to find the nearest ancestor that has the property registered in its data context (`init$` or `add$()`):
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
- ### Named data contexts
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
- Inspired by native HTML `name` attributes - like how `<input name="group">` groups radio buttons - the `ctx` attribute groups components into a shared data context. Components with the same `ctx` value share `*`-prefixed properties:
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 - no parent component, no prop drilling, no global store boilerplate. Just set `ctx="gallery"` in HTML and use `*`-prefixed properties. This makes it trivial to build complex component relationships purely in markup, with ready-made components that don't need to know about each other.
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 Styling
251
+ ### CSS styling
204
252
 
205
- Shadow DOM is **optional** in Symbiote - use it when you need isolation, skip it when you don't. This gives full flexibility:
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
- **Light DOM** - style components with regular CSS, no barriers:
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
- This style will be applied to nearest upper shadow root, if exists and to common document if not.
268
+ Symbiote.js applies this style to the nearest containing shadow root, when one exists, or to the document.
221
269
 
222
- **Shadow DOM** - opt-in isolation when needed:
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
- All native CSS features work as expected: CSS variables flow through shadow boundaries, `::part()` exposes internals, modern nesting, `@layer`, `@container` - no framework abstractions in the way. Mix light DOM and shadow DOM components freely in the same app.
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 Data
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
- - **Complex widgets** embedded in any host application
256
- - **Low-code HTML-based solutions** - simple declarative everything
257
- - **Micro frontends** - standard custom elements, no framework coupling
258
- - **Reusable component libraries** - works in React, Vue, Angular, or plain HTML
259
- - **SSR-powered apps** - lightweight server rendering without framework lock-in
260
- - **Framework-agnostic solutions** - one codebase, any context
261
- - **Modern AI-first web** - expose the application state to WebMCP tools automatically
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 & Examples
311
+ ## Docs and examples
264
312
 
265
313
  - [Documentation](https://github.com/symbiotejs/symbiote.js/blob/main/docs/README.md)
266
- - [Live Examples](https://rnd-pro.com/symbiote/3x/examples/) - Interactive Code Playground
267
- - [JSDA-Kit](https://github.com/rnd-pro/jsda-kit) - All-in-one companion tool: server, SSG, bundling, import maps, and native Symbiote.js SSR integration
268
- - [AI / llms.txt](https://rnd-pro.com/symbiote/llms.txt) — index for AI tools
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
- **Questions or proposals? Welcome to [Symbiote Discussions](https://github.com/symbiotejs/symbiote.js/discussions)!** ❤️
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) - MIT License
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>} kvObj
377
- * @param {Boolean} [forcePrimitives] Force update callbacks for primitive types
393
+ * @param {Partial<S>} stateObj
378
394
  */
379
- set$(kvObj, forcePrimitives = false) {
380
- for (let key in kvObj) {
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() {
@@ -175,7 +175,8 @@ function domBindProcessor(fr, fnCtx) {
175
175
  el.setAttribute(prop, val);
176
176
  }
177
177
  } else {
178
- if (!setNestedProp(el, prop, val)) {
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?.controller?.abort();
377
+ deactivateEntry(entry);
352
378
  tools.delete(publicName);
353
379
  }
354
380
 
@@ -356,7 +382,7 @@ function updateOwnerEntry(ownerIdVal, entry) {
356
382
  webMCPRegistry.store.owners.add(ownerIdVal, entry, true);
357
383
  }
358
384
 
359
- function registerNativeTool(publicName, toolEntry, descriptor, owner, executor) {
385
+ function registerNativeTool(publicName, toolEntry, descriptor) {
360
386
  let modelContext = getModelContext();
361
387
  setDiagnostic('apiAvailable', !!modelContext);
362
388
  if (!modelContext) {
@@ -371,15 +397,7 @@ function registerNativeTool(publicName, toolEntry, descriptor, owner, executor)
371
397
  description: toolEntry.description,
372
398
  inputSchema: toolEntry.inputSchema,
373
399
  execute(input = {}) {
374
- try {
375
- let result = executor(input || {});
376
- if (result?.then) {
377
- return result.catch(errorResponse);
378
- }
379
- return result;
380
- } catch (e) {
381
- return errorResponse(e);
382
- }
400
+ return executeEntry(toolEntry, input);
383
401
  },
384
402
  };
385
403
  if (descriptor.annotations) {
@@ -421,7 +439,13 @@ function makeEntryWithComponentDescription(publicName, key, descriptor, owner, e
421
439
  nativeActive: false,
422
440
  controller: null,
423
441
  };
424
- let native = registerNativeTool(publicName, entry, descriptor, owner, executor);
442
+ toolExecutors.set(entry, (input) => {
443
+ if ((isElementOwner(owner) && !owner.isConnected) || !shouldRegister(descriptor, owner)) {
444
+ return unavailableTool(publicName);
445
+ }
446
+ return executor(input);
447
+ });
448
+ let native = registerNativeTool(publicName, entry, descriptor);
425
449
  entry.controller = native.controller;
426
450
  entry.nativeActive = native.nativeActive;
427
451
  return entry;
@@ -471,10 +495,13 @@ function createAutoDesired(owner, key, eventBinding = null) {
471
495
  throw new Error(`Handler "${key}" is not available on <${tagName}>.`);
472
496
  }
473
497
  let result = handler.call(owner, syntheticEvent(eventBinding?.el));
474
- let suffix = result ? `: ${result}` : '';
475
- return textResponse(
476
- `Response status - ok${suffix}\nDetails: ${JSON.stringify(stateSnapshot(owner))}`
477
- );
498
+ let respond = (value) => {
499
+ let suffix = value ? `: ${value}` : '';
500
+ return textResponse(
501
+ `Response status - ok${suffix}\nDetails: ${JSON.stringify(stateSnapshot(owner))}`
502
+ );
503
+ };
504
+ return result?.then ? Promise.resolve(result).then(respond) : respond(result);
478
505
  },
479
506
  });
480
507
  return {
@@ -667,6 +694,8 @@ export function registerWebMCPTool(owner, key, descriptor) {
667
694
  return entry.then((resolvedEntry) => {
668
695
  if (isCurrentOwnerVersion(owner, version)) {
669
696
  webMCPRegistry.store.tools.add(publicName, resolvedEntry, true);
697
+ } else {
698
+ deactivateEntry(resolvedEntry);
670
699
  }
671
700
  return resolvedEntry;
672
701
  }).catch((e) => {
@@ -782,6 +811,18 @@ export function getActiveWebMCPTools() {
782
811
  return Object.keys(tools).map((name) => serializeEntry(tools[name]));
783
812
  }
784
813
 
814
+ /**
815
+ * Invoke a currently registered tool without requiring native browser WebMCP.
816
+ * Input validation and transport authorization belong to the caller.
817
+ * @param {string} name
818
+ * @param {Object} [input]
819
+ * @returns {any | Promise<any>}
820
+ */
821
+ export function executeWebMCPTool(name, input = {}) {
822
+ let tools = webMCPRegistry.store.tools;
823
+ return executeEntry(tools.has(name) ? tools.read(name) : undefined, input, name);
824
+ }
825
+
785
826
  /** @param {typeof Symbiote} [SymbioteClass] */
786
827
  export function installWebMCP(SymbioteClass = Symbiote) {
787
828
  if (installedClasses.has(SymbioteClass)) {
@@ -825,4 +866,5 @@ export default {
825
866
  unregisterWebMCPTools,
826
867
  syncWebMCPTools,
827
868
  getActiveWebMCPTools,
869
+ executeWebMCPTool,
828
870
  };
package/docs/README.md CHANGED
@@ -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 Experimental**](./webmcp.md) — Expose live UI state and handlers as browser-native tools
32
+ - [**WebMCP**](./webmcp.md) — Expose live UI state and handlers as browser-native tools
33
33
  - [**Routing**](./routing.md) — SPA routing with path patterns, guards, lazy loading
34
34
  - [**SSR**](./ssr.md) — Server-side rendering, streaming, hydration
35
35
  - [**SSR and Your Server Setup**](./ssr-server.md) — Static build, streaming, Express or Fastify
@@ -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) — Trusted Types and CSP compliance
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
- - [llms.txt](https://rnd-pro.com/symbiote/llms.txt) — index for AI tools
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
 
@@ -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 change multiple property values at once, use the `set$` method:
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
- ## Trusted Types
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
- Symbiote.js is compatible with strict Content Security Policy (CSP) headers that require [Trusted Types](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API).
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
- // Symbiote creates a passthrough policy automatically:
10
- // trustedTypes.createPolicy('symbiote', { createHTML: (s) => s })
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
- To use Symbiote.js with strict Trusted Types:
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
- The policy name is `'symbiote'`.
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 { SSR } from '@symbiotejs/symbiote/node/SSR.js';
48
+ import { randomBytes } from 'node:crypto';
49
+ import { SSR } from '@symbiotejs/symbiote/node';
31
50
 
32
- let nonce = crypto.randomUUID(); // generate per request
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
- > On the client side, Symbiote.js applies styles via `adoptedStyleSheets`, which is CSP-safe and requires no nonce.
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