@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 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
@@ -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 the DOM synchronously. No virtual DOM, no scheduling, no surprises. And since components are real DOM elements, state is accessible from the outside via standard APIs:
110
+ State changes update bound DOM properties synchronously, without a virtual DOM or scheduler. Because components are real DOM elements, their state is also accessible through standard APIs:
85
111
 
86
112
  ```js
87
113
  document.querySelector('my-counter').$.count = 42;
88
114
  ```
89
115
 
90
- This makes it easy to control Symbiote-based widgets and microfrontends from any host application - no framework adapters, just DOM.
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
- The `^` prefix works in any nested component template - it walks up the DOM tree to find the nearest ancestor that has the property registered in its data context (`init$` or `add$()`):
140
+ In a nested component template, the `^` prefix walks up the DOM tree and finds the nearest ancestor with the requested property in its data context (`init$` or `add$()`):
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
- ### Named data contexts
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
- Inspired by native HTML `name` attributes - like how `<input name="group">` groups radio buttons - the `ctx` attribute groups components into a shared data context. Components with the same `ctx` value share `*`-prefixed properties:
171
+ Shared contexts follow the same idea as the native HTML `name` attribute used to group radio buttons. The `ctx` attribute assigns components to a shared data context, and components with the same value can use the same `*`-prefixed properties:
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 - 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.
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 Styling
212
+ ### CSS styling
204
213
 
205
- Shadow DOM is **optional** in Symbiote - use it when you need isolation, skip it when you don't. This gives full flexibility:
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
- **Light DOM** - style components with regular CSS, no barriers:
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
- This style will be applied to nearest upper shadow root, if exists and to common document if not.
229
+ Symbiote.js applies this style to the nearest containing shadow root, when one exists, or to the document.
221
230
 
222
- **Shadow DOM** - opt-in isolation when needed:
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
- All native CSS features work as expected: CSS variables flow through shadow boundaries, `::part()` exposes internals, modern nesting, `@layer`, `@container` - no framework abstractions in the way. Mix light DOM and shadow DOM components freely in the same app.
242
+ Native CSS features remain available. CSS variables cross shadow boundaries, `::part()` exposes selected internals, and modern nesting, `@layer`, and `@container` work without framework abstractions. Light DOM and Shadow DOM components can coexist in the same application.
234
243
 
235
- ### CSS Data
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
- - **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
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 & Examples
272
+ ## Docs and examples
264
273
 
265
274
  - [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
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
- **Questions or proposals? Welcome to [Symbiote Discussions](https://github.com/symbiotejs/symbiote.js/discussions)!** ❤️
287
+ Questions and proposals are welcome in [Symbiote Discussions](https://github.com/symbiotejs/symbiote.js/discussions).
279
288
 
280
289
  ---
281
290
 
282
- © [rnd-pro.com](https://rnd-pro.com) - MIT License
291
+ © [rnd-pro.com](https://rnd-pro.com), MIT License
package/core/webmcp.js CHANGED
@@ -45,6 +45,9 @@ import { parseProp } from './parseProp.js';
45
45
  const REGISTRY_UID = Symbol.for('symbiote.webmcp.registry');
46
46
  let ownerIdCount = 0;
47
47
 
48
+ /** @type {WeakMap<object, (input: Object) => any>} */
49
+ let toolExecutors = new WeakMap();
50
+
48
51
  /** @type {WeakMap<object, Array<{remove: Function}>>} */
49
52
  let ownerDeps = new WeakMap();
50
53
  /** @type {WeakSet<typeof Symbiote>} */
@@ -82,6 +85,29 @@ function errorResponse(error) {
82
85
  };
83
86
  }
84
87
 
88
+ function unavailableTool(name) {
89
+ return errorResponse(new Error(`WebMCP tool "${name}" is not available.`));
90
+ }
91
+
92
+ function executeEntry(entry, input, name = entry?.name) {
93
+ let executor = entry && toolExecutors.get(entry);
94
+ if (!entry?.active || !executor) {
95
+ return unavailableTool(name);
96
+ }
97
+ try {
98
+ let result = executor(input || {});
99
+ return result?.then ? Promise.resolve(result).catch(errorResponse) : result;
100
+ } catch (error) {
101
+ return errorResponse(error);
102
+ }
103
+ }
104
+
105
+ function deactivateEntry(entry) {
106
+ entry.active = false;
107
+ toolExecutors.delete(entry);
108
+ entry.controller?.abort();
109
+ }
110
+
85
111
  function textResponse(text) {
86
112
  return {
87
113
  content: [{
@@ -348,7 +374,7 @@ function unregisterToolName(publicName) {
348
374
  return;
349
375
  }
350
376
  let entry = tools.read(publicName);
351
- entry?.controller?.abort();
377
+ deactivateEntry(entry);
352
378
  tools.delete(publicName);
353
379
  }
354
380
 
@@ -356,7 +382,7 @@ function updateOwnerEntry(ownerIdVal, entry) {
356
382
  webMCPRegistry.store.owners.add(ownerIdVal, entry, true);
357
383
  }
358
384
 
359
- function registerNativeTool(publicName, toolEntry, descriptor, owner, executor) {
385
+ function registerNativeTool(publicName, toolEntry, descriptor) {
360
386
  let modelContext = getModelContext();
361
387
  setDiagnostic('apiAvailable', !!modelContext);
362
388
  if (!modelContext) {
@@ -371,15 +397,7 @@ function registerNativeTool(publicName, toolEntry, descriptor, owner, executor)
371
397
  description: toolEntry.description,
372
398
  inputSchema: toolEntry.inputSchema,
373
399
  execute(input = {}) {
374
- try {
375
- let result = executor(input || {});
376
- if (result?.then) {
377
- return result.catch(errorResponse);
378
- }
379
- return result;
380
- } catch (e) {
381
- return errorResponse(e);
382
- }
400
+ return executeEntry(toolEntry, input);
383
401
  },
384
402
  };
385
403
  if (descriptor.annotations) {
@@ -421,7 +439,13 @@ function makeEntryWithComponentDescription(publicName, key, descriptor, owner, e
421
439
  nativeActive: false,
422
440
  controller: null,
423
441
  };
424
- let native = registerNativeTool(publicName, entry, descriptor, owner, executor);
442
+ toolExecutors.set(entry, (input) => {
443
+ if ((isElementOwner(owner) && !owner.isConnected) || !shouldRegister(descriptor, owner)) {
444
+ return unavailableTool(publicName);
445
+ }
446
+ return executor(input);
447
+ });
448
+ let native = registerNativeTool(publicName, entry, descriptor);
425
449
  entry.controller = native.controller;
426
450
  entry.nativeActive = native.nativeActive;
427
451
  return entry;
@@ -471,10 +495,13 @@ function createAutoDesired(owner, key, eventBinding = null) {
471
495
  throw new Error(`Handler "${key}" is not available on <${tagName}>.`);
472
496
  }
473
497
  let result = handler.call(owner, syntheticEvent(eventBinding?.el));
474
- let suffix = result ? `: ${result}` : '';
475
- return textResponse(
476
- `Response status - ok${suffix}\nDetails: ${JSON.stringify(stateSnapshot(owner))}`
477
- );
498
+ let respond = (value) => {
499
+ let suffix = value ? `: ${value}` : '';
500
+ return textResponse(
501
+ `Response status - ok${suffix}\nDetails: ${JSON.stringify(stateSnapshot(owner))}`
502
+ );
503
+ };
504
+ return result?.then ? Promise.resolve(result).then(respond) : respond(result);
478
505
  },
479
506
  });
480
507
  return {
@@ -667,6 +694,8 @@ export function registerWebMCPTool(owner, key, descriptor) {
667
694
  return entry.then((resolvedEntry) => {
668
695
  if (isCurrentOwnerVersion(owner, version)) {
669
696
  webMCPRegistry.store.tools.add(publicName, resolvedEntry, true);
697
+ } else {
698
+ deactivateEntry(resolvedEntry);
670
699
  }
671
700
  return resolvedEntry;
672
701
  }).catch((e) => {
@@ -782,6 +811,18 @@ export function getActiveWebMCPTools() {
782
811
  return Object.keys(tools).map((name) => serializeEntry(tools[name]));
783
812
  }
784
813
 
814
+ /**
815
+ * Invoke a currently registered tool without requiring native browser WebMCP.
816
+ * Input validation and transport authorization belong to the caller.
817
+ * @param {string} name
818
+ * @param {Object} [input]
819
+ * @returns {any | Promise<any>}
820
+ */
821
+ export function executeWebMCPTool(name, input = {}) {
822
+ let tools = webMCPRegistry.store.tools;
823
+ return executeEntry(tools.has(name) ? tools.read(name) : undefined, input, name);
824
+ }
825
+
785
826
  /** @param {typeof Symbiote} [SymbioteClass] */
786
827
  export function installWebMCP(SymbioteClass = Symbiote) {
787
828
  if (installedClasses.has(SymbioteClass)) {
@@ -825,4 +866,5 @@ export default {
825
866
  unregisterWebMCPTools,
826
867
  syncWebMCPTools,
827
868
  getActiveWebMCPTools,
869
+ executeWebMCPTool,
828
870
  };
package/docs/README.md CHANGED
@@ -29,7 +29,7 @@
29
29
 
30
30
  ## Features
31
31
 
32
- - [**WebMCP Experimental**](./webmcp.md) — Expose live UI state and handlers as browser-native tools
32
+ - [**WebMCP**](./webmcp.md) — Expose live UI state and handlers as browser-native tools
33
33
  - [**Routing**](./routing.md) — SPA routing with path patterns, guards, lazy loading
34
34
  - [**SSR**](./ssr.md) — Server-side rendering, streaming, hydration
35
35
  - [**SSR and Your Server Setup**](./ssr-server.md) — Static build, streaming, Express or Fastify
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
- 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.
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
- Here are the three most important differences between Symbiote.js and other frameworks:
8
- 1. **Natural DOM Extension Philosophy** - designed to extend platform APIs, not to replace them
9
- 2. **Runtime-Agnostic HTML Templates** - outstanding flexibility for rendering strategies and further customization
10
- 3. **Powerful App-wide State Management** - combine data contexts without bloated boilerplate or external tools
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
- - **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).
15
- - **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.
16
- - **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.
17
- - **Computed properties refined** - reactive derived state with microtask batching.
18
- - **Path-based router** - optional `AppRouter` module with `:param` extraction, route guards, and lazy loading.
19
- - **Exit animations** - `animateOut(el)` for CSS-driven exit transitions, integrated into itemize API.
20
- - **Dev mode** - `Symbiote.devMode` enables verbose warnings; import `devMessages.js` for full human-readable messages.
21
- - **DSD hydration** - `ssrMode` supports both light DOM and Declarative Shadow DOM.
22
- - **Class property fallback** - binding keys not in `init$` fall back to own class properties/methods.
23
- - **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.
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
- No install needed - run this directly in a browser:
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
- Or install via npm:
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 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:
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
- This makes it easy to control Symbiote-based widgets and microfrontends from any host application - no framework adapters, just DOM.
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
- 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$()`):
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
- ### Named data contexts
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
- 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:
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 - 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.
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 Styling
207
+ ### CSS styling
199
208
 
200
- Shadow DOM is **optional** in Symbiote - use it when you need isolation, skip it when you don't. This gives full flexibility:
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
- **Light DOM** - style components with regular CSS, no barriers:
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
- This style will be applied to nearest upper shadow root, if exists and to common document if not.
224
+ Symbiote.js applies this style to the nearest containing shadow root, when one exists, or to the document.
216
225
 
217
- **Shadow DOM** - opt-in isolation when needed:
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
- 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.
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 Data
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
- - **Complex widgets** embedded in any host application
251
- - **Low-code HTML-based solutions** - simple declarative everything
252
- - **Micro frontends** - standard custom elements, no framework coupling
253
- - **Reusable component libraries** - works in React, Vue, Angular, or plain HTML
254
- - **SSR-powered apps** - lightweight server rendering without framework lock-in
255
- - **Framework-agnostic solutions** - one codebase, any context
256
- - **Modern AI-first web** - expose the application state to WebMCP tools automatically
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 & Examples
267
+ ## Docs and examples
259
268
 
260
269
  - [Documentation](https://github.com/symbiotejs/symbiote.js/blob/main/docs/README.md)
261
- - [Live Examples](https://rnd-pro.com/symbiote/3x/examples/) - Interactive Code Playground
262
- - [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
263
- - [AI / llms.txt](https://rnd-pro.com/symbiote/llms.txt) — index for AI tools
264
- - [Full docs (single file)](https://rnd-pro.com/symbiote/llms-full.txt) — complete merged reference for AI context
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
- **Questions or proposals? Welcome to [Symbiote Discussions](https://github.com/symbiotejs/symbiote.js/discussions)!** ❤️
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) - MIT License
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.2",
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": "npx playwright test",
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 && npx playwright test && npm run test:webmcp:native"
18
+ "test": "node --test test/node/*.test.js && playwright test && npm run test:webmcp:native"
18
19
  },
19
20
  "files": [
20
21
  "core/*",
@@ -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":"AAqoBA,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,CAmC9I;AA2CD,uCADY,GAAG,QA6Bd;AAGD,6CADY,GAAG,QAyBd;AAGD,wCADc,mBAAmB,EAAE,CAIlC;AAGD,8CADY,OAAO,QAAQ,QA+B1B;AA3ND;IAKE,sBADY,qBAAqB,EAWhC;IARC,aAAwB;IACxB,gCAvkB6B,GAAG,KAAK,MAAM,EAukBsB;IACjE,iBAAuD;IAEvD,eAvkBmB,GAAG,KAAK,OAAO,CAukBV;IACxB,eAA8B;IAC9B,oBAAkC;IAClC,iBAAsC;IASxC,4BAJW,GAAG,UACH,KAAK,GACH,GAAG,CAOf;;CACF;AAED,yCAUK;;;;;;;;;;;;UArnBS,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"}
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"}