@symbiotejs/symbiote 3.8.0-webmcp.2 → 3.8.1

package/README.md

@@ -1,24 +1,27 @@
 [![Tests](https://github.com/symbiotejs/symbiote.js/actions/workflows/tests.yml/badge.svg)](https://github.com/symbiotejs/symbiote.js/actions/workflows/tests.yml)
 [![npm version](https://img.shields.io/npm/v/@symbiotejs/symbiote)](https://www.npmjs.com/package/@symbiotejs/symbiote)
 [![npm downloads](https://img.shields.io/npm/dm/@symbiotejs/symbiote)](https://www.npmjs.com/package/@symbiotejs/symbiote)
-![bundle size](https://img.shields.io/badge/brotli-7.3_kb-blue)
-![types](https://img.shields.io/badge/types-JSDoc+d.ts-blue)
 ![license](https://img.shields.io/badge/license-MIT-green)
 
 # Symbiote.js
 
 <img src="https://rnd-pro.com/svg/symbiote/index.svg" width="200" alt="Symbiote.js">
 
-A lightweight, standards-first UI library built on Web Components. No virtual DOM, no compiler, no build step required - works directly in the browser. A bundler is recommended for production performance, but entirely optional. **~7.3kb** brotli / **~8.1kb** gzip.
+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.
 
-Symbiote.js gives you the convenience of a modern framework while staying close to the native platform - HTML, CSS, and DOM APIs. Components are real custom elements that work everywhere: in any framework, in plain HTML, or in a micro-frontend architecture. And with **isomorphic mode**, the same component code works on the server and the client - server-rendered pages hydrate automatically, no diffing, no mismatch errors.
+Symbiote.js gives you the convenience of a modern framework while staying close to the native platform - HTML, CSS, and DOM APIs. Components are custom elements that work everywhere: in any framework, in plain HTML, in a micro-frontend architecture. And with **isomorphic mode**, the same component code works on the server and the client - server-rendered pages hydrate automatically, no diffing, no mismatch errors.
 
-## What's new?
+Here are the three most important differences between Symbiote.js and other frameworks:
+1. Natural DOM Extension Philosophy - designed to extend platform, not to replace it
+2. Runtime-Agnostic HTML Templates - outstanding flexibility for rendering strategies and further customization
+3. Powerful App-wide State Management - combine data contexts without bloated boilerplate or external tools
 
-- **Experimental 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).
+## What's new in v3.x?
+
+- **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).
 - **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.
 - **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.
-- **Computed properties** - reactive derived state with microtask batching.
+- **Computed properties refined** - reactive derived state with microtask batching.
 - **Path-based router** - optional `AppRouter` module with `:param` extraction, route guards, and lazy loading.
 - **Exit animations** - `animateOut(el)` for CSS-driven exit transitions, integrated into itemize API.
 - **Dev mode** - `Symbiote.devMode` enables verbose warnings; import `devMessages.js` for full human-readable messages.
@@ -336,18 +339,7 @@ CSS values are parsed automatically - quoted strings become strings, numbers bec
 - **Reusable component libraries** - works in React, Vue, Angular, or plain HTML
 - **SSR-powered apps** - lightweight server rendering without framework lock-in
 - **Framework-agnostic solutions** - one codebase, any context
-
-## Bundle size
-
-| Library | Minified | Gzip | Brotli |
-|---------|----------|------|--------|
-| **Symbiote.js** (core) | 23.6 kb | 8.1 kb | **7.3 kb** |
-| **Symbiote.js** (full, with AppRouter + WebMCP export) | 35.6 kb | 12.1 kb | **11.0 kb** |
-| **Symbiote.js** (WebMCP extension) | 31.4 kb | 10.6 kb | **9.6 kb** |
-| **Lit** 3.3 | 15.5 kb | 6.0 kb | **~5.1 kb** |
-| **React 19 + ReactDOM** | ~186 kb | ~59 kb | **~50 kb** |
-
-Symbiote and Lit have similar base sizes, but Symbiote's **7.3 kb** core includes more built-in features: global state management, lists (itemize API), exit animations, computed properties etc. Lit needs additional packages for comparable features. React is **~7× larger** before adding a router, state manager, or SSR framework.
+- **Modern AI-first web** - expose the application state to WebMCP tools automatically
 
 ## Browser support
 
@@ -359,7 +351,8 @@ All modern browsers: Chrome, Firefox, Safari, Edge, Opera.
 - [Lit vs Symbiote.js](https://github.com/symbiotejs/symbiote.js/blob/main/docs/lit-vs-symbiote.md) - Side-by-side comparison
 - [Live Examples](https://rnd-pro.com/symbiote/3x/examples/) - Interactive Code Playground
 - [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
-- [AI Reference](https://github.com/symbiotejs/symbiote.js/blob/main/AI_REFERENCE.md)
+- [AI / llms.txt](https://rnd-pro.com/symbiote/llms.txt) — index for AI tools
+- [Full docs (single file)](https://rnd-pro.com/symbiote/llms-full.txt) — complete merged reference for AI context
 - [Changelog](https://github.com/symbiotejs/symbiote.js/blob/main/CHANGELOG.md)
 
 ## Related articles

package/core/webmcp.js

@@ -22,7 +22,7 @@ import { parseProp } from './parseProp.js';
  * @property {string | ((owner?: any) => string)} [description]
  * @property {Object | ((owner?: any) => Object)} [inputSchema]
  * @property {(args?: Object, owner?: any, event?: Event) => any} [execute]
- * @property {() => boolean} [when]
+ * @property {(owner?: any) => boolean} [when]
  * @property {string[]} [deps]
  * @property {string[]} [exposedTo]
  * @property {Object} [annotations]
@@ -53,6 +53,7 @@ let installedClasses = new WeakSet();
 let pendingOwnerSync = new WeakSet();
 /** @type {WeakMap<object, number>} */
 let ownerVersions = new WeakMap();
+let _modelContext;
 
 function isToolDescriptor(val) {
   return !!val?.[DICT.MCP_TOOL_DESCRIPTOR_MARKER];
@@ -244,13 +245,16 @@ function ownerId(owner) {
 }
 
 function getModelContext() {
+  if (_modelContext) return _modelContext;
   let docCtx = /** @type {any} */ (globalThis.document)?.modelContext;
   if (docCtx?.registerTool) {
-    return docCtx;
+    _modelContext = docCtx;
+    return _modelContext;
   }
   let navCtx = /** @type {any} */ (globalThis.navigator)?.modelContext;
   if (navCtx?.registerTool) {
-    return navCtx;
+    _modelContext = navCtx;
+    return _modelContext;
   }
   return null;
 }
@@ -591,13 +595,16 @@ function scheduleOwnerSync(owner) {
 }
 
 export class ToolDescriptor {
+  /** @type {((args?: Object, owner?: any, event?: Event) => any) | undefined} */
+  #fn;
+
   /** @param {ToolDescriptorOptions} options */
   constructor(options = {}) {
     this[DICT.MCP_TOOL_DESCRIPTOR_MARKER] = true;
     this.name = options.name;
     this.description = options.description || 'Symbiote WebMCP tool.';
     this.inputSchema = options.inputSchema || emptySchema();
-    this.fn = options.execute;
+    this.#fn = options.execute;
     this.when = options.when;
     this.deps = options.deps || [];
     this.exposedTo = options.exposedTo;
@@ -611,15 +618,15 @@ export class ToolDescriptor {
    * @returns {any}
    */
   execute(args = {}, owner, event) {
-    if (typeof this.fn !== 'function') {
+    if (typeof this.#fn !== 'function') {
       throw new Error('ToolDescriptor requires an execute function.');
     }
-    return this.fn.call(owner, args || {}, owner, event);
+    return this.#fn.call(owner, args || {}, owner, event);
   }
 }
 
 export const webMCPRegistry = (() => {
-  let existing = PubSub.getCtx(REGISTRY_UID, false);
+  let existing = PubSub.getCtx(REGISTRY_UID);
   let root = existing || PubSub.registerCtx({}, REGISTRY_UID);
   ensureNestedCtx(root, 'tools');
   ensureNestedCtx(root, 'owners');
@@ -662,32 +669,23 @@ export function registerWebMCPTool(owner, key, descriptor) {
         webMCPRegistry.store.tools.add(publicName, resolvedEntry, true);
       }
       return resolvedEntry;
+    }).catch((e) => {
+      setDiagnostic('lastError', e);
+      throw e;
     });
   }
   webMCPRegistry.store.tools.add(publicName, entry, true);
   return entry;
 }
 
-/** @param {any} owner */
-export function syncWebMCPTools(owner) {
-  if (!owner) return;
-  if (isElementOwner(owner) && !owner.isConnected) {
-    unregisterWebMCPTools(owner);
-    return;
-  }
-  let version = bumpOwnerVersion(owner);
-  let id = ownerId(owner);
-  let desired = collectDesiredTools(owner);
-  setupDeps(owner, desired);
-  let owners = webMCPRegistry.store.owners;
-  let ownerEntry = owners.has(id)
-    ? owners.read(id)
-    : {
-      ownerId: id,
-      ownerType: ownerType(owner),
-      ownerName: ownerName(owner),
-      toolsByKey: {},
-    };
+/**
+ * @param {any} owner
+ * @param {string} id
+ * @param {{ownerId: string, ownerType: string, ownerName: string, toolsByKey: Record<string, string>}} ownerEntry
+ * @param {Array<{key: string, baseName: string, descriptor: ToolDescriptor, executor: Function}>} desired
+ * @param {string} componentDescription
+ */
+function applyDesiredTools(owner, id, ownerEntry, desired, componentDescription) {
   let nextKeys = new Set();
   for (let item of desired) {
     nextKeys.add(item.key);
@@ -703,17 +701,9 @@ export function syncWebMCPTools(owner) {
     if (hasToolName(publicName)) {
       unregisterToolName(publicName);
     }
-    let entry = makeEntry(publicName, item.key, item.descriptor, owner, item.executor);
+    let entry = makeEntryWithComponentDescription(publicName, item.key, item.descriptor, owner, item.executor, componentDescription);
     ownerEntry.toolsByKey[item.key] = publicName;
-    if (entry instanceof Promise) {
-      entry.then((resolvedEntry) => {
-        if (isCurrentOwnerVersion(owner, version)) {
-          webMCPRegistry.store.tools.add(publicName, resolvedEntry, true);
-        }
-      });
-    } else {
-      webMCPRegistry.store.tools.add(publicName, entry, true);
-    }
+    webMCPRegistry.store.tools.add(publicName, entry, true);
   }
   for (let key in ownerEntry.toolsByKey) {
     if (!nextKeys.has(key)) {
@@ -723,9 +713,40 @@ export function syncWebMCPTools(owner) {
   }
   if (Object.keys(ownerEntry.toolsByKey).length) {
     updateOwnerEntry(id, ownerEntry);
-  } else if (owners.has(id)) {
-    owners.delete(id);
+  } else if (webMCPRegistry.store.owners.has(id)) {
+    webMCPRegistry.store.owners.delete(id);
+  }
+}
+
+/** @param {any} owner */
+export function syncWebMCPTools(owner) {
+  if (!owner) return;
+  if (isElementOwner(owner) && !owner.isConnected) {
+    unregisterWebMCPTools(owner);
+    return;
+  }
+  let version = bumpOwnerVersion(owner);
+  let id = ownerId(owner);
+  let desired = collectDesiredTools(owner);
+  setupDeps(owner, desired);
+  let owners = webMCPRegistry.store.owners;
+  let ownerEntry = owners.has(id)
+    ? owners.read(id)
+    : {
+      ownerId: id,
+      ownerType: ownerType(owner),
+      ownerName: ownerName(owner),
+      toolsByKey: {},
+    };
+  let componentDescription = readComponentDescription(owner);
+  if (typeof componentDescription !== 'string') {
+    componentDescription.then((resolved) => {
+      if (!isCurrentOwnerVersion(owner, version)) return;
+      applyDesiredTools(owner, id, ownerEntry, desired, resolved);
+    }).catch((e) => setDiagnostic('lastError', e));
+    return;
   }
+  applyDesiredTools(owner, id, ownerEntry, desired, componentDescription);
 }
 
 /** @param {any} owner */

package/docs/README.md

@@ -0,0 +1,62 @@
+# Symbiote.js Documentation
+
+> **Version 3.x** — A lightweight, standards-first UI library built on Web Components.
+> Zero dependencies. ~7.3 KB brotli / ~8.1 KB gzip. No virtual DOM, no compiler, no build step required.
+
+## Getting Started
+
+- [**Get Started**](./get-started.md) — Installation, first component, platform specs
+- [**Ecosystem**](./ecosystem.md) — IDE setup, build tools, code sharing
+
+## Core Concepts
+
+- [**Templates**](./templates.md) — HTML string templates, binding syntax, slots, element references
+- [**Properties**](./properties.md) — State initialization, `$` proxy, subscriptions, computed properties
+- [**Context**](./context.md) — Local, named, pop-up, and shared data contexts
+- [**List Rendering**](./list-rendering.md) — Itemize API for dynamic lists
+- [**Lifecycle**](./lifecycle.md) — Component lifecycle callbacks and destruction
+- [**Flags**](./flags.md) — Component configuration flags
+- [**Attributes**](./attributes.md) — HTML attribute binding and observation
+
+## State Management
+
+- [**PubSub**](./pubsub.md) — Standalone state management, named contexts
+
+## Styling
+
+- [**Styling**](./styling.md) — rootStyles, shadowStyles, CSS processing
+- [**CSS Data**](./css-data.md) — CSS custom properties as reactive state
+
+## Features
+
+- [**WebMCP Experimental**](./webmcp.md) — Expose live UI state and handlers as browser-native tools
+- [**Routing**](./routing.md) — SPA routing with path patterns, guards, lazy loading
+- [**SSR**](./ssr.md) — Server-side rendering, streaming, hydration
+- [**SSR and Your Server Setup**](./ssr-server.md) — Static build, streaming, Express or Fastify
+- [**Animations**](./animations.md) — CSS-driven exit transitions
+
+## Development
+
+- [**Dev Mode**](./dev-mode.md) — Verbose warnings for debugging
+- [**TypeScript**](./typescript.md) — JSDoc types, TypeScript usage, and hybrid template checks
+- [**Security**](./security.md) — Trusted Types and CSP compliance
+
+## Migration
+
+- [**2.x → 3.x Migration Guide**](./migration-2x-to-3x.md) — Breaking changes and upgrade path
+
+## Additional Resources
+
+- [Lit vs Symbiote.js](./lit-vs-symbiote.md) — Side-by-side comparison
+- [Live Examples](https://rnd-pro.com/symbiote/3x/examples/) - Interactive Code Playground
+- [Common Mistakes](./common-mistakes.md) — Patterns that frequently cause bugs
+- [Examples](./examples.md) — 26 complete working examples
+- [llms.txt](https://rnd-pro.com/symbiote/llms.txt) — index for AI tools
+- [llms-full.txt](https://rnd-pro.com/symbiote/llms-full.txt) — complete merged reference for AI context
+- [Changelog](../CHANGELOG.md)
+- [npm](https://www.npmjs.com/package/@symbiotejs/symbiote)
+- [GitHub Discussions](https://github.com/symbiotejs/symbiote.js/discussions)
+
+---
+
+© [rnd-pro.com](https://rnd-pro.com) — MIT License

package/docs/animations.md

@@ -0,0 +1,61 @@
+# Animations
+
+Symbiote.js provides CSS-driven exit transitions with zero JS animation code.
+
+## `animateOut`
+
+`animateOut(el)` sets the `[leaving]` attribute on an element, waits for CSS `transitionend`, then removes the element from the DOM. If no CSS transition is defined, removes immediately.
+
+```js
+import { animateOut } from '@symbiotejs/symbiote';
+
+// or as a static method:
+Symbiote.animateOut(el);
+```
+
+## CSS pattern
+
+Use `@starting-style` for enter animations and `[leaving]` for exit:
+```css
+my-item {
+  opacity: 1;
+  transform: translateY(0);
+  transition: opacity 0.3s, transform 0.3s;
+
+  /* Enter (CSS-native, no JS needed): */
+  @starting-style {
+    opacity: 0;
+    transform: translateY(20px);
+  }
+
+  /* Exit (triggered by animateOut): */
+  &[leaving] {
+    opacity: 0;
+    transform: translateY(-10px);
+  }
+}
+```
+
+## Itemize integration
+
+Both itemize processors use `animateOut` automatically for item removal. Items with CSS `transition` + `[leaving]` styles will animate out before being removed from the DOM:
+```css
+user-card {
+  opacity: 1;
+  transition: opacity 0.3s;
+
+  @starting-style {
+    opacity: 0;
+  }
+
+  &[leaving] {
+    opacity: 0;
+  }
+}
+```
+
+No additional JavaScript is required — just define the CSS transitions and Symbiote handles the rest.
+
+---
+
+Next: [CSS Data →](./css-data.md)

package/docs/attributes.md

@@ -0,0 +1,85 @@
+# Attributes
+
+Like all regular DOM elements, Symbiote components can have their own HTML attributes. And like standard Custom Elements, they can react to dynamic attribute changes.
+
+## Attribute connection
+
+The simplest way to connect a local state property to an attribute value is with the `@` token:
+```js
+class MyComponent extends Symbiote {
+
+  init$ = {
+    '@attribute-name': 'initial value',
+  }
+
+}
+```
+
+Or initiate from the component's template directly:
+```js
+class MyComponent extends Symbiote {}
+
+MyComponent.template = html`<h1>{{@attribute-name}}</h1>`;
+```
+
+Then use it as an attribute in markup:
+```html
+<my-component attribute-name="attribute value"></my-component>
+```
+
+## Attribute change reaction
+
+Using a property accessor:
+```js
+class MyComponent extends Symbiote {
+
+  set 'my-attribute'(val) {
+    console.log(val);
+  }
+
+}
+
+MyComponent.observedAttributes = [
+  'my-attribute',
+];
+```
+
+## `bindAttributes()` static method
+
+Bind attributes to property values directly:
+```js
+class MyComponent extends Symbiote {
+
+  init$ = {
+    myProp: '',
+  }
+
+}
+
+// Map the attribute name to corresponding property key:
+MyComponent.bindAttributes({
+  'my-attribute': 'myProp',
+});
+
+// observedAttributes is auto-populated
+
+MyComponent.template = html`
+  <div>{{myProp}}</div>
+`;
+```
+
+## Reserved attribute names
+
+These attribute names are used internally by Symbiote.js:
+
+- `bind`
+- `ctx`
+- `ref`
+- `itemize`
+- `item-tag`
+- `use-template`
+- `skip-text-nodes`
+
+---
+
+Next: [PubSub →](./pubsub.md)