@symbiotejs/symbiote 3.8.0-webmcp.2 → 3.8.0

package/README.md

@@ -359,7 +359,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/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)

package/docs/common-mistakes.md

@@ -0,0 +1,267 @@
+# Common Mistakes
+
+Patterns that frequently trip up new users and AI code generators.
+
+---
+
+## 1. Using `this` inside template strings
+
+Templates are context-free strings — they DO NOT execute inside a component instance and do not close over `this`. Binding values by name; the component resolves them at render time.
+
+```js
+// WRONG
+MyComponent.template = html`<div>${this.title}</div>`;
+
+// CORRECT — use binding syntax
+MyComponent.template = html`<div>{{title}}</div>`;
+// OR
+MyComponent.template = html`<div ${{textContent: 'title'}}></div>`;
+// OR
+MyComponent.template = `<div bind="textContent: title"></div>`;
+```
+
+---
+
+## 2. Defining `template`, `rootStyles`, or `shadowStyles` inside the class body
+
+`template`, `rootStyles`, and `shadowStyles` are **static property setters** on the `Symbiote` base class — not regular static fields. Assigning them inside the class body with `static template = ...` bypasses the setter and does nothing.
+
+```js
+// WRONG
+class MyComponent extends Symbiote {
+  static template = html`<div>{{text}}</div>`; // setter never called
+}
+
+// CORRECT — assign outside the class body
+class MyComponent extends Symbiote {}
+MyComponent.template = html`<div>{{text}}</div>`;
+MyComponent.rootStyles = css`my-component { display: block; }`;
+```
+
+---
+
+## 3. Missing `^` prefix when referencing a parent-defined handler from an item template
+
+Itemize items are real Symbiote components with their own reactive state (the data properties mapped from the source array or object). They can have their own handlers too — either passed as functions in the source data objects, or defined on a separate component class registered for the tag name set by `item-tag` attribute.
+
+The common mistake is defining a shared handler on the **parent** (e.g. to handle all item clicks in one place) and then binding to it from the item template *without* `^`. Without `^`, the binding looks for the handler on the item itself — where it doesn't exist — and fails.
+
+```js
+class MyList extends Symbiote {
+  init$ = {
+    items: [{ name: 'Alice' }, { name: 'Bob' }],
+    onItemClick: (e) => { console.log('clicked'); },
+  }
+}
+
+// WRONG — looks for onItemClick on the item, not the parent
+MyList.template = html`
+  <ul itemize="items">
+    <template>
+      <li><button ${{onclick: 'onItemClick'}}>{{name}}</button></li>
+    </template>
+  </ul>
+`;
+
+// CORRECT — ^ walks up the DOM to find onItemClick in the parent's init$
+MyList.template = html`
+  <ul itemize="items">
+    <template>
+      <li><button ${{onclick: '^onItemClick'}}>{{name}}</button></li>
+    </template>
+  </ul>
+`;
+```
+
+> `^`-targeted properties must be defined in the ancestors's `init$` — the walk does not check plain class properties.
+
+When each item needs its own independent handler, you can pass it directly in the data:
+```js
+this.$.items = [
+  { name: 'Alice', onItemClick: () => console.log('Alice clicked') },
+  { name: 'Bob',   onItemClick: () => console.log('Bob clicked') },
+];
+```
+```html
+<ul itemize="items">
+  <template>
+    <li><button ${{onclick: 'onItemClick'}}>{{name}}</button></li>
+  </template>
+</ul>
+```
+
+Or, as it recommended for the most cases, register a dedicated component class for the tag name set by `item-tag`:
+```js
+class MyItem extends Symbiote {
+  onItemClick() { console.log(this.$.name); }
+}
+MyItem.template = html`<li><button ${{onclick: 'onItemClick'}}>{{name}}</button></li>`;
+MyItem.reg('my-item');
+```
+```html
+<ul itemize="items" item-tag="my-item"></ul>
+```
+
+---
+
+## 4. Using `@` attribute prefix directly in HTML
+
+`@` is a binding syntax prefix only — it means "bind to HTML attribute" inside `${{}}` expressions. It is not a valid HTML attribute prefix.
+
+```html
+<!-- WRONG -->
+<div @hidden="isHidden">...</div>
+
+<!-- CORRECT — @-prefix is only inside binding objects -->
+<div ${{'@hidden': 'isHidden'}}>...</div>
+<!-- OR, when html template helper is not used: -->
+<div bind="@hidden': isHidden">...</div>
+```
+
+---
+
+## 5. Expecting dotted `init$` keys to create nested state
+
+State is flat by design. A key like `'obj.prop'` in `init$` is a literal flat key named `obj.prop` — it does not create a nested object `{ obj: { prop: ... } }`. `this.$['obj.prop']` reads and writes that same flat key and works fine.
+
+```js
+// MISLEADING — this does NOT create { obj: { prop: 'value' } }
+init$ = { 'obj.prop': 'value' };
+// It creates a flat key: store['obj.prop'] = 'value'
+// Reading/writing it works: this.$['obj.prop'] = 'new' ✓
+
+// If you need a nested object in state, store it as a flat key with an object value:
+init$ = { obj: { prop: 'value' } };
+this.$.obj = { ...this.$.obj, prop: 'new' }; // replace the whole object to trigger reactivity
+```
+
+Dot notation in binding **targets** is fully supported — for both standard DOM properties and child component state:
+```js
+// DOM property path:
+html`<div ${{'style.color': 'colorProp'}}>Text</div>`
+
+// Child component's $ state proxy:
+html`<child-el ${{'$.childProp': 'parentProp'}}></child-el>`
+```
+
+---
+
+## 6. Using `*prop` without a `ctx` attribute or `--ctx` CSS variable
+
+Shared context properties (`*`-prefix) require a context name to be set on the component — either via the `ctx` HTML attribute or the `--ctx` CSS custom property. Without one, `*` props silently have no effect (dev mode warns).
+
+```html
+<!-- WRONG — no context name, *files is never shared -->
+<upload-btn></upload-btn>
+<file-list></file-list>
+
+<!-- CORRECT -->
+<upload-btn ctx="gallery"></upload-btn>
+<file-list  ctx="gallery"></file-list>
+```
+
+---
+
+## 7. Expecting Shadow DOM by default
+
+Shadow DOM is opt-in. By default, templates render into the component's light DOM. Use `renderShadow = true` or assign `shadowStyles` to opt in.
+
+```js
+// Light DOM (default)
+class MyComponent extends Symbiote {}
+
+// Shadow DOM — either flag:
+class MyComponent extends Symbiote {
+  renderShadow = true;
+}
+// or via shadowStyles (auto-creates shadow root):
+MyComponent.shadowStyles = css`:host { display: block; }`;
+```
+
+---
+
+## 8. Adding a wrapper div inside the template
+
+The custom element itself is the container. Adding a wrapping `<div>` as the single root inside the template is unnecessary — it creates extra DOM nesting and duplicates the element's own box. Style the component tag directly instead.
+
+```js
+// WRONG — the <div class="wrapper"> is redundant, my-widget is already the root
+MyWidget.template = html`
+  <div class="wrapper">
+    <h1>{{title}}</h1>
+    <button ${{onclick: 'onAction'}}>Go</button>
+  </div>
+`;
+
+// CORRECT — template content renders directly inside the custom element
+MyWidget.template = html`
+  <h1>{{title}}</h1>
+  <button ${{onclick: 'onAction'}}>Go</button>
+`;
+```
+
+```css
+/* Style the element tag directly */
+my-widget {
+  display: block;
+  padding: 20px;
+}
+```
+
+---
+
+## 9. Relying on class property fallbacks for prefixed bindings
+
+Class property fallbacks (resolving unregistered keys from own instance properties or prototype methods) only apply to **local, unprefixed** bindings. Any prefixed binding — `^prop`, `*prop` — resolves exclusively through the data context (`init$` or `add$()`). Plain class properties are never checked for these.
+
+```js
+// WRONG — onItemClick is a class property, not in init$
+// ^ will not find it
+class TaskList extends Symbiote {
+  onItemClick() { console.log('clicked'); }
+}
+
+TaskList.template = html`
+  <ul itemize="tasks">
+    <template>
+      <li ${{onclick: '^onItemClick'}}>{{name}}</li>
+    </template>
+  </ul>
+`;
+
+// CORRECT — register in init$ so any prefixed binding can resolve it
+class TaskList extends Symbiote {
+  init$ = {
+    onItemClick: () => { console.log('clicked'); },
+  }
+}
+```
+
+The same applies to shared (`*`) bindings — the property must exist in the shared context's registered data, not merely as a class property. 
+
+Named external contexts (`CTX/prop`) are different: they are registered globally via `PubSub.registerCtx()` and are fully independent of any component's `init$` — components reference them freely without declaring anything locally.
+
+---
+
+## 10. Treating `init$` as a plain object
+
+`init$` is processed once at connection time to populate the component's reactive context. Mutating it after the fact has no effect. Use `this.$` or `add$()` for runtime changes.
+
+```js
+// WRONG — modifying init$ after construction does nothing
+class MyComponent extends Symbiote {
+  init$ = { count: 0 };
+  initCallback() {
+    this.init$.count = 10; // too late, already processed
+  }
+}
+
+// CORRECT
+class MyComponent extends Symbiote {
+  init$ = { count: 0 };
+  initCallback() {
+    this.$.count = 10; // write through the $ proxy
+  }
+}
+```
+