@symbiotejs/symbiote 3.8.0 → 3.8.2

package/llms.txt

@@ -8,7 +8,6 @@ Symbiote.js extends HTMLElement natively. State changes update the DOM synchrono
 
 - [Full documentation (single file)](https://rnd-pro.com/symbiote/llms-full.txt): Complete merged reference — paste this into any AI tool for full context
 - [README](https://github.com/symbiotejs/symbiote.js/blob/main/README.md): Overview, quick start, and feature summary
-- [Changelog](https://github.com/symbiotejs/symbiote.js/blob/main/CHANGELOG.md): Version history
 
 ## Core concepts
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@symbiotejs/symbiote",
-  "version": "3.8.0",
+  "version": "3.8.2",
   "description": "Symbiote.js - zero-dependency close-to-platform frontend library to build super-powered web components",
   "author": "team@rnd-pro.com",
   "license": "MIT",
@@ -24,7 +24,6 @@
     "scripts/*",
     "docs/*",
     "README.md",
-    "CHANGELOG.md",
     "LICENSE",
     "llms.txt",
     "llms-full.txt"

package/scripts/build-llms.js

@@ -11,8 +11,6 @@ const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const EXCLUDE_DOCS = new Set([
   'README.md',             // index only, no content
   'ecosystem.md',          // IDE/tooling setup, not API
-  'lit-vs-symbiote.md',    // comparison article
-  'migration-2x-to-3x.md', // migration guide
   'llms-index.md',         // llms.txt template — not merged into llms-full.txt
 ]);
 

package/types/core/webmcp.d.ts

@@ -12,12 +12,12 @@ export class ToolDescriptor {
     name: string;
     description: string | ((owner?: any) => string);
     inputSchema: any;
-    fn: (args?: any, owner?: any, event?: Event) => any;
-    when: () => boolean;
+    when: (owner?: any) => boolean;
     deps: string[];
     exposedTo: string[];
     annotations: any;
     execute(args?: any, owner?: any, event?: Event): any;
+    #private;
 }
 export const webMCPRegistry: PubSub<any>;
 declare namespace _default {
@@ -43,7 +43,7 @@ export type ToolDescriptorOptions = {
     description?: string | ((owner?: any) => string);
     inputSchema?: any | ((owner?: any) => any);
     execute?: (args?: any, owner?: any, event?: Event) => any;
-    when?: () => boolean;
+    when?: (owner?: any) => boolean;
     deps?: string[];
     exposedTo?: string[];
     annotations?: any;

package/types/core/webmcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webmcp.d.ts","sourceRoot":"","sources":["../../core/webmcp.js"],"names":[],"mappings":"AA8nBA,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,CAgC9I;AAGD,uCADY,GAAG,QA0Dd;AAGD,6CADY,GAAG,QAyBd;AAGD,wCADc,mBAAmB,EAAE,CAIlC;AAGD,8CADY,OAAO,QAAQ,QA+B1B;AA1MD;IAEE,sBADY,qBAAqB,EAWhC;IARC,aAAwB;IACxB,gCAhkB6B,GAAG,KAAK,MAAM,EAgkBsB;IACjE,iBAAuD;IACvD,yBAhkBkC,GAAG,UAAU,KAAK,KAAK,GAAG,CAgkBnC;IACzB,YAhkBgB,OAAO,CAgkBC;IACxB,eAA8B;IAC9B,oBAAkC;IAClC,iBAAsC;IASxC,4BAJW,GAAG,UACH,KAAK,GACH,GAAG,CAOf;CACF;AAED,yCAUK;;;;;;;;;;;;UA9mBS,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,MAAM,OAAO;WACb,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"}
+{"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"}

package/CHANGELOG.md

@@ -1,372 +0,0 @@
-# Changelog
-
-## 3.8.0
-
-### Added
-
-- **Experimental WebMCP support.** New optional `@symbiotejs/symbiote/webmcp` entry point exposes live Symbiote UI actions as native browser WebMCP tools. Import it before rendering participating components, then use `mcpToolMode` for automatic event-handler tools or `ToolDescriptor` for custom descriptions, input schemas, execution, and `when()` visibility.
-
-- **Component context for agents.** Components can define `componentDescription` as a string or async function. The resolved text is appended to component-owned tool descriptions.
-
-- **WebMCP lifecycle registration.** Component tools register on render and unregister on DOM removal. Itemized components inherit global `mcpToolMode`, keyed item tools include `_KEY_` context, and popup `^` event bindings can expose ancestor-owned tools with source item context.
-
-### Notes
-
-- This is an experimental release intended for browser builds with native WebMCP support, such as Chrome Canary 150. Publish with the `webmcp` npm tag while the API stabilizes.
-
-## 3.7.0
-
-### Added
-
-- Self-Closing Custom Elements
-
-Now this compact format is supported for tagged templates:
-```js
-html`<my-component />`;
-```
-
-### Improved
-
-- Documentation update
-
-## 3.5.4
-
-### Fixed
-
-- **SSR: `bindAttributes()` crash in linkedom.** `observedAttributes` is a getter-only property in linkedom — direct assignment threw. Now uses `Object.defineProperty` with a configurable getter.
-
-- **SSR: `renderCallback()` crash from browser-only APIs.** Components using `IntersectionObserver`, `window.location`, etc. in `renderCallback` crashed the entire SSR process. Now wrapped in try-catch during SSR (`__SYMBIOTE_SSR`); browser-side errors still re-throw normally.
-
-## 3.5.2
-
-### Fixed
-
-- **`devMode` flag is now cross-module safe.** Moved to `globalThis.__SYMBIOTE_DEV_MODE` so it works correctly across CDN/importmap module scopes (same pattern as `PubSub.globalStore`).
-
-### Improved
-
-- **`warn.js` — minimal core dispatcher.** Stripped to just `devState`, `warnMsg`, and `errMsg`. All formatting, messages, and styling logic moved to `devMessages.js` via `globalThis.__SYMBIOTE_DEV_LOG` handler. No messages map or `Array.isArray` in core.
-
-- **Colored console output.** `devMessages.js` now renders styled badges in browser consoles: purple `Symbiote` badge, amber/red code badge, violet `<component-name>`, and dimmed doc links. Falls back to plain text in Node.js.
-
-- **Doc references in all warnings.** Every message now includes a `→` link to the relevant GitHub docs page.
-
-- **`devMessages.js` auto-enables `devMode`.** Importing the module sets `globalThis.__SYMBIOTE_DEV_MODE = true` — one import for the full dev experience.
-
-## 3.5.0
-
-### Added
-
-- **External dev messages module (`core/devMessages.js`).** All warning and error message strings have been extracted from core files into an optional module. Core files now emit short numeric codes (e.g. `[Symbiote W5]`). Import `@symbiotejs/symbiote/core/devMessages.js` once to get full human-readable messages. This reduces the core bundle size by removing all formatting strings from `PubSub.js`, `Symbiote.js`, `tpl-processors.js`, `AppRouter.js`, `html.js`, and both itemize processors.
-
-- **`core/warn.js` — lightweight message dispatcher.** Exports `warnMsg(code, ...args)` and `errMsg(code, ...args)`. All core files now use this dispatcher instead of inline `console.warn`/`console.error` calls.
-
-- **AppRouter: `title` accepts functions.** Route descriptors and `setDefaultTitle()` now accept `() => String` in addition to plain strings. The function is called at navigation time, enabling dynamic or localized page titles:
-  ```js
-  AppRouter.setDefaultTitle(() => i18n('app.title'));
-  AppRouter.initRoutingCtx('R', {
-    home: { pattern: '/', title: () => i18n('home.title'), default: true },
-  });
-  ```
-
-## 3.4.7
-
-### Fixed
-
-- **PubSub: computed properties with cross-context deps no longer depend on import order.** When a computed property declared `deps: ['CTX/prop']` and the target context wasn't registered yet, the subscription was silently skipped. Now deferred deps are stored in `PubSub.pendingDeps` and automatically resolved when `registerCtx()` is called.
-- **Symbiote: named context access no longer crashes when context is not yet registered.** The `$` proxy, `sub()`, `notify()`, `has()`, and `add()` now handle missing named contexts gracefully (return `undefined`/no-op instead of throwing).
-- **Symbiote: template bindings for named contexts are deferred when context is not yet registered.** Previously, `sub()` silently dropped the subscription; now it queues it via `PubSub.pendingDeps` and resolves automatically when `registerCtx()` is called.
-
-## 3.4.4
-
-### Fixed
-
-- **SSR: `isVirtual` components.** `renderToString` and `renderToStream` now detect `isVirtual` elements and serialize the replacement template nodes instead of the detached custom element wrapper. Previously, virtual components produced an empty `<tag-name></tag-name>` in SSR output.
-
-- **SSR: `allowCustomTemplate` with `use-template` attribute.** `DocumentFragment` detection in `render()` used `constructor === DocumentFragment`, which fails in linkedom where `template.content.cloneNode()` returns a fragment with a different internal constructor. Changed to `nodeType === 11` — spec-correct and works in both browser and linkedom. Previously, custom templates were silently ignored during SSR.
-
-## 3.4.3
-
-### Fixed
-
-- **SSR: shared context props (`*prop`) with `ctx` attribute.** `getCssData()` attempted `window.getComputedStyle()` during server-side rendering, which is unavailable in linkedom. Now returns `null` immediately when `globalThis.__SYMBIOTE_SSR` is set, skipping all computed CSS reads on the server.
-
-### Added
-
-- **DevMode warning for CSS data bindings in SSR/ISO mode.** When `devMode = true` and the component has `ssrMode` or `isoMode`, a `console.warn` fires for each `bindCssData` call — computed styles are unavailable during SSR, so the init value is used instead.
-
-## 3.4.2
-
-### Fixed
-
-- **isoMode: Shadow DOM components with Light DOM slot children.** `isoMode` checked `this.childNodes` to detect SSR content, but for Shadow DOM components Light DOM children are slot content — not server-rendered shadow tree. This caused template rendering to be skipped. Now checks `this.shadowRoot.childNodes` for Shadow DOM components and `this.childNodes` for Light DOM ones.
-
-## 3.4.1
-
-### Fixed
-
-- **SSR: `{{prop}}` text-node bindings with class property fallback.** `resolveTextTokens` now checks own class properties and prototype methods when the prop is not in `init$`. Previously, linkedom's `DocumentFragment.textContent` returning `null` caused `txtNodesProcessor` to skip processing, and the serializer fallback only resolved `init$` props — leaving raw `{{prop}}` tokens in SSR output.
-
-## 3.4.0
-
-### Added
-
-- **DevMode warning for `{{prop}}` in SSR/ISO mode.** Text-node bindings produce no `bind=` attribute in SSR output, so they render correctly on the server but cannot be hydrated on the client. When `devMode = true` and the component has `ssrMode` or `isoMode` enabled, a `console.warn` now suggests using `${{textContent: 'prop'}}` for hydratable text.
-
-## 3.3.9
-
-### Improved
-
-- **DRY itemize processors.** Extracted shared setup logic (element discovery, SSR hydration, class creation, template derivation, attribute cleanup) into `itemizeSetup.js`. Both `itemizeProcessor.js` and `itemizeProcessor-keyed.js` now use the same setup, eliminating code duplication.
-
-- **Keyed processor SSR support.** `itemizeProcessor-keyed.js` now inherits all SSR hydration fixes: `clientSSR` detection, SSR tag adoption, `isoMode` on items, static template derivation, conditional child clearing, and `initPropFallback`.
-
-### Fixed
-
-- **Keyed processor: live HTMLCollection bug.** Fixed `animateOut` failing when removing multiple items by key — the live `HTMLCollection` shifted indices during removal. Elements are now snapshotted before removal.
-
-## 3.3.8
-
-### Fixed
-
-- **SSR hydration: Itemize template derivation.** Dynamically added itemize items now use the original template (parsed from `fnCtx.constructor.template`) instead of SSR-expanded `innerHTML`. This preserves nested custom elements (e.g. icons) in new items added after hydration.
-
-## 3.3.7
-
-### Fixed
-
-- **SSR hydration: Itemize list duplication.**
-  Fixed itemize SSR hydration creating duplicate items. The processor now adopts the existing SSR item tag name and element class, skips the initial subscription fire, and sets `isoMode` on the item class so upgraded elements hydrate their existing content instead of re-rendering.
-
-## 3.3.6
-
-### Improved
-
-- **SSR hydration: generic property preservation.**
-  During SSR/ISO hydration, all primitive-valued bindings (`textContent`, `innerHTML`, `style.*`, `value`, etc.) now skip the initial write, preserving server-rendered DOM. Function bindings (event handlers) and non-null object bindings (component state) still fire immediately. Previously only `textContent` and attribute bindings were preserved.
-
-- **SSR hydration: Itemize API support.**
-  Auto-generated itemize item components now inherit `ssrMode`/`isoMode` from the parent. Server-rendered list items are preserved during hydration instead of being cleared and re-created.
-
-## 3.3.5
-
-### Fixed
-
-- **AppRouter: SSR context populated with default route.**
-  `initRoutingCtx()` in SSR now populates the PubSub context with the default route's `route`, `title`, and `options` instead of leaving them as `null`. Components can access `this.$['R/route']` during server rendering.
-
-## 3.3.4
-
-### Fixed
-
-- **PubSub context isolation with importmaps.**
-  `PubSub.globalStore` now uses `globalThis.__SYMBIOTE_PUBSUB_STORE`, so multiple copies of PubSub loaded from different URLs (e.g. via importmap) share the same context registry. Fixes `Router/title` and similar named context bindings not working when AppRouter is resolved separately.
-
-### Added
-
-- **`@symbiotejs/symbiote/full` entry point.**
-  Re-exports everything from the main entry point plus `AppRouter`, guaranteeing a single PubSub module:
-  ```js
-  import Symbiote, { html, css, AppRouter } from '@symbiotejs/symbiote/full';
-  ```
-
-- **AppRouter SSR support.**
-  `AppRouter.initRoutingCtx()` now works in Node.js and linkedom SSR environments — creates the PubSub context without errors, skipping browser-only APIs (`window`, `history`, events). Enables isomorphic code that uses AppRouter on both server and client.
-
-## 3.3.0
-
-### Added
-
-- **`isoMode` flag for isomorphic rendering.**
-  `isoMode = true` enables automatic detection: if the component has children at connect time (server-rendered content), it hydrates existing DOM like `ssrMode`. If no children exist, it renders the template normally. Same component code works for both SSR and client-only scenarios.
-
-## 3.2.0
-
-### Added
-
-- **Itemize class property fallback.**
-  The `itemize` data source property now supports class property fallback, consistent with `domBindProcessor` and `txtNodesProcessor`.
-
-### Changed
-
-- **Utils moved to separate entry point.**
-  `UID`, `setNestedProp`, `applyStyles`, `applyAttributes`, `create`, `kebabToCamel`, `reassignDictionary` are no longer exported from the main `@symbiotejs/symbiote` entry point. Import from `@symbiotejs/symbiote/utils` instead:
-  ```js
-  import { UID, create } from '@symbiotejs/symbiote/utils';
-  ```
-  Individual deep imports (`@symbiotejs/symbiote/utils/UID.js`, etc.) continue to work.
-
-- **`initPropFallback` extracted to shared module.**
-  Duplicated fallback initialization logic across template processors consolidated into `core/initPropFallback.js`.
-
-## 3.1.0
-
-### Changed
-
-- **Class property fallback (generalized).**
-  Bindings not found in `init$` now fall back to own class properties (checked via `Object.hasOwn`), not just `on*` event handlers. Functions are auto-bound to the component instance. Inherited `HTMLElement` properties are never picked up.
-  ```js
-  class MyComp extends Symbiote {
-    label = 'Click me';
-    onSubmit() { console.log('submitted'); }
-  }
-  ```
-  Previously only `on*` handlers supported this fallback.
-
-## 3.0.0
-
-### ⚠️ Breaking Changes
-
-- **`tplProcessors` → `templateProcessors`.**
-  The `addTemplateProcessor()` method is removed — use native `Set` methods:
-  ```js
-  // 2.x:
-  this.addTemplateProcessor(myProcessor);
-  // 3.x:
-  this.templateProcessors.add(myProcessor);
-  ```
-
-- **`AppRouter.applyRoute()` → `AppRouter.navigate()`.**
-
-- **`AppRouter` removed from main entry point.**
-  ```js
-  // 2.x:
-  import { AppRouter } from '@symbiotejs/symbiote';
-  // 3.x:
-  import { AppRouter } from '@symbiotejs/symbiote/core/AppRouter.js';
-  ```
-
-- **Computed properties: cross-context requires explicit deps.**
-  Local computeds (same-context) keep working unchanged. Cross-context now uses object syntax:
-  ```js
-  // 2.x — implicit via global scan:
-  init$ = {
-    '+total': () => this.$['APP/score'] + this.$.local,
-  };
-  // 3.x — explicit deps:
-  init$ = {
-    '+total': {
-      deps: ['APP/score'],
-      fn: () => this.$['APP/score'] + this.$.local,
-    },
-  };
-  ```
-
-- **Shared context (`*prop`) simplified.**
-  Removed `ctxOwner` / `ctx-owner`. First-registered value always wins. Dev-mode warnings when `*prop` used without `ctx` attribute.
-
-### Performance
-
-- **Computed properties: per-instance dependency tracking.**
-  Replaced global scan with per-instance auto-tracking. Up to **676× faster** for local computeds, **14×** for sparse scenarios.
-
-- **Microtask batching.**
-  All computed recalculation and internal scheduling uses `queueMicrotask` instead of `setTimeout`.
-
-- **`#parseProp` fast path.**
-  `charCodeAt` checks skip full string parsing for common local properties — the most frequent case.
-
-- **`$` proxy inlined fast path.**
-  Both `get` and `set` traps bypass `#parseProp` entirely for local props.
-
-- **`PubSub.pub()` direct value pass.**
-  Eliminates redundant `read()` on every state update.
-
-- **Dev warnings gated by `PubSub.devMode`.**
-  Type-mismatch checks have zero overhead in production.
-
-- **`txtNodesProcessor` early exit.**
-  Skips text-node scanning when template contains no `{{` tokens.
-
-- **`localCtx` direct construction.**
-  Uses `new PubSub({})` instead of `PubSub.registerCtx({})`, bypassing global store for component-scoped state.
-
-- **`hasOwnProperty` → `in` operator** across `PubSub` internals.
-
-- **`itemizeProcessor-keyed.js` — optional optimized itemize processor.**
-  Drop-in replacement with reference-equality fast paths and key-based reconciliation. Up to **3× faster** for appends, **2×** for in-place updates, **32×** for no-ops:
-  ```js
-  import { itemizeProcessor } from '@symbiotejs/symbiote/core/itemizeProcessor-keyed.js';
-  import { itemizeProcessor as defaultProcessor } from '@symbiotejs/symbiote/core/itemizeProcessor.js';
-
-  class BigList extends Symbiote {
-    constructor() {
-      super();
-      this.templateProcessors.delete(defaultProcessor);
-      this.templateProcessors = new Set([itemizeProcessor, ...this.templateProcessors]);
-    }
-  }
-  ```
-
-### Added
-
-- **Server-side rendering (`node/SSR.js`).**
-  `SSR` class with static methods for server-side rendering. `SSR.processHtml(html)` renders any HTML string with embedded components. `SSR.renderToString(tagName, attrs?)` renders a single component. `SSR.renderToStream(tagName, attrs?)` async generator yields HTML chunks. Declarative Shadow DOM with inlined styles. rootStyles emitted as `<style>` tags in light DOM. Light DOM content preserved. Binding attributes preserved for client hydration. `linkedom` is an optional peer dependency.
-  ```js
-  import { SSR } from '@symbiotejs/symbiote/node/SSR.js';
-  await SSR.init();
-  await import('./my-app.js');
-  let html = await SSR.processHtml('<my-app>content</my-app>');
-  SSR.destroy();
-  ```
-
-- **Declarative Shadow DOM hydration (`ssrMode`).**
-  `ssrMode = true` hydrates pre-rendered content (light DOM + `<template shadowrootmode>`). Template injection skipped; bindings attach to existing DOM. Shadow styles applied via `adoptedStyleSheets`.
-
-- **Exit animation hook (`animateOut`).**
-  Sets `[leaving]` attribute, waits for CSS `transitionend`, removes element. Integrated into itemize processors — items with transitions animate out automatically. Enter animations use `@starting-style`.
-
-- **`AppRouter`: path-based routing.**
-  Routes with `pattern` key use path-based URLs with `:param` extraction:
-  ```js
-  AppRouter.initRoutingCtx('R', {
-    home: { pattern: '/', title: 'Home', default: true },
-    user: { pattern: '/users/:id', title: 'User' },
-  });
-  // /users/42 → { route: 'user', options: { id: '42' } }
-  ```
-  Query-string routes remain fully backward compatible.
-
-- **Route guards — `AppRouter.beforeRoute(fn)`.**
-  Return `false` to cancel, a route string to redirect:
-  ```js
-  let unsub = AppRouter.beforeRoute((to, from) => {
-    if (!isAuth && to.route === 'settings') return 'login';
-  });
-  ```
-
-- **Lazy loaded routes.**
-  `load` in route descriptors for dynamic imports, cached automatically:
-  ```js
-  { pattern: '/settings', load: () => import('./pages/settings.js') }
-  ```
-
-- **Class property fallback.**
-  Bindings not in `init$` fall back to own class properties/methods:
-  ```js
-  label = 'Click me';
-  onSubmit() { console.log('submitted'); }
-  ```
-
-- **`Symbiote.devMode` flag.**
-  Enables verbose warnings (unresolved bindings, tag names, available contexts). Also wires `PubSub.devMode`.
-
-- **`reg()` returns the class itself.**
-  Enables `export default MyComponent.reg('my-component')`.
-
-- **`destructionDelay` instance property.**
-  Configurable delay (default `100`ms) before cleanup in `disconnectedCallback`.
-
-- **Trusted Types support.**
-  Template writes use `'symbiote'` Trusted Types policy when available. Zero overhead otherwise.
-
-- **`this` in template detection.**
-  `html` fires `console.error` when `${this.…}` used in template (templates are context-free).
-
-- **AI_REFERENCE.md** — comprehensive context file for code assistants.
-
-### Fixed
-
-- `css()` trailing `undefined` when no interpolations exist.
-- `new DocumentFragment()` → `document.createDocumentFragment()` for linkedom compatibility.
-- `txtNodesProcessor` null check for `fr.textContent` in SSR environments.

package/docs/lit-vs-symbiote.md

@@ -1,200 +0,0 @@
-# Lit vs Symbiote.js
-
-> [!NOTE]
-> Both libraries build on Web Components. Lit is the most popular choice backed by Google. So why consider Symbiote.js?
-
-This comparison is written from the Symbiote.js perspective but aims to be technically fair. Where Lit does something well, we say so.
-
-## At a Glance
-
-| | **Symbiote.js 3.x** | **Lit 3.x** |
-|--|--|--|
-| **Core size** (brotli) | ~7.3 kb | ~5.1 kb |
-| **Full bundle** (brotli) | ~11.0 kb (core + router + WebMCP export) | ~5.1 kb + addons |
-| **Dependencies** | 0 runtime | 0 runtime |
-| **Shadow DOM** | Opt-in per component | On by default |
-| **SSR** | Built-in (`node/SSR.js`) | Experimental (`@lit-labs/ssr`) |
-| **Routing** | Built-in (optional import) | Not included |
-| **State management** | Built-in (PubSub, contexts) | Separate package (`@lit/context`) |
-| **Build step** | Not required | Not required |
-| **TypeScript** | JSDoc + `.d.ts` | Decorators-first API |
-
-> Lit's base size is ~2 kb smaller, but Symbiote's core already includes state management, list rendering (Itemize API), computed properties, and exit animations — features that in the Lit ecosystem require additional packages.
-
-## Templates
-
-This is the biggest architectural difference.
-
-### Lit
-
-Templates use the `html` tagged template literal with JavaScript expressions bound to the current component's `this`:
-
-```js
-html`<p>${this.message}</p>`
-html`<button @click=${this.onClick}>Click</button>`
-```
-
-- Expressions are tied to the component's render method and its `this` scope.
-- Templates are re-evaluated on every render cycle.
-- The `html` function does not produce a plain HTML string — it returns a `TemplateResult` object processed by Lit's internal rendering pipeline.
-- Templates cannot be separated from the JavaScript execution context.
-
-### Symbiote.js
-
-Templates are plain HTML strings with declarative binding attributes. They are context-free — they do not reference `this`:
-
-```js
-html`<p>{{message}}</p>`
-html`<button ${{onclick: 'onClick'}}>Click</button>`
-```
-
-Key advantages:
-
-1. **Runtime-independent** — templates are standard HTML strings. They can live in separate files, arrive from an API response, or be embedded directly in the page markup.
-2. **Decoupled from `this`** — bindings use property name strings, not direct references. A component provides data and handlers; a template defines presentation independently.
-3. **Multiple template sources** — the same component can use different templates from the document via `use-template` attribute, enabling complete separation of data logic and representation.
-4. **Dual-mode interpolation** — `html` supports both reactive bindings (objects) and standard string interpolation in a single template.
-5. **Loose-coupling alternative** — templates can be written as pure HTML without any JavaScript context at all: `<div bind="textContent: myProp"></div>`.
-6. **SSR-transparent** — the `html` function produces clean HTML with `bind=` attributes that can be rendered server-side by any template engine, or by Symbiote's own SSR module, and hydrated on the client. No special markers, no `<!--lit-part-->` comments.
-
-## Server-Side Rendering
-
-### Lit
-
-SSR is experimental and lives in `@lit-labs/ssr`. A working setup requires:
-
-- `@lit-labs/ssr` — server-side renderer
-- `@lit-labs/ssr-client` — client-side hydration support (including `lit-element-hydrate-support.js`)
-- `@lit-labs/ssr-dom-shim` — DOM polyfills for the server
-
-Important constraints:
-- **Load order matters** — `lit-element-hydrate-support.js` must be loaded _before_ the `lit` module and all components.
-- **Hydration mismatches** — server and client renders must produce identical output, or errors occur.
-- **No async support** — Lit SSR has no built-in mechanism to wait for async results before serializing.
-- **Comment-based markers** — the output contains `<!--lit-part-->` and `<!--lit-node-->` comments for template re-association.
-
-### Symbiote.js
-
-SSR is built in (one module, `node/SSR.js`) with `linkedom` as an optional peer dependency:
-
-```js
-import { SSR } from '@symbiotejs/symbiote/node/SSR.js';
-
-await SSR.init();
-await import('./my-app.js');
-
-let result = await SSR.processHtml('<my-app></my-app>');
-SSR.destroy();
-```
-
-Key differences:
-- **1 module** — no separate client/server packages.
-- **No hydration mismatches** — the server produces HTML with `bind=` attributes. The client reads those attributes and attaches reactivity. There's no diffing, so there's nothing to mismatch.
-- **Streaming** — `SSR.renderToStream()` yields HTML chunks for lower TTFB.
-- **`isoMode`** — one flag makes a component isomorphic: hydrates if server content exists, renders from template otherwise. No conditional logic.
-- **Clean output** — no framework markers in the HTML.
-- **CSP nonce support** — pass `{ nonce }` to add nonce attributes to generated `<style>` tags.
-
-## Data Flow and State Management
-
-### Lit
-
-- **Reactive properties** — declared with `@property()` decorator. Changes trigger re-render cycle.
-- **Internal state** — `@state()` decorator for private reactive properties.
-- **Data sharing** — `@lit/context` package implements the W3C Context Community Protocol. Uses `@provide`/`@consume` decorators and DOM events under the hood. This is a separate install.
-- **No global state** — Lit does not include global state management; you bring your own (Redux, MobX, signals).
-
-### Symbiote.js
-
-Symbiote provides a layered data context system built in — no extra packages:
-
-| Context | Token | Description |
-|---------|-------|-------------|
-| **Local** | `myProp` | Component's own reactive state |
-| **Pop-up (`^`)** | `^parentProp` | Walks up the DOM tree to find the nearest ancestor with the property. Works like CSS cascade |
-| **Shared (`*`)** | `*sharedProp` | Components with the same `ctx` attribute share state. No parent component or prop drilling needed |
-| **Named** | `APP/myProp` | Global named data contexts accessible by key from anywhere |
-| **CSS Data** | `--my-var` | Initialize component state from CSS custom property values |
-| **Computed** | `+sum` | Reactive derived state with microtask batching |
-
-The outstanding simplicity here is that a component can bind directly to any external data context without adding a single line of component logic. Just use the prefix in the template — `{{APP/user}}`, `{{^parentTitle}}`, `{{*sharedCount}}` — and the binding is established. No decorator setup, no provider/consumer wiring, no subscription boilerplate. The template _is_ the wiring.
-
-In Lit, achieving the same patterns requires a combination of `@property()` declarations, `@provide`/`@consume` decorators from a separate `@lit/context` package, custom events, and often an external state management library.
-
-## CSS and Styling
-
-### Lit
-
-- Shadow DOM is the default — styles are scoped and isolated.
-- Styles are defined in the component class via `static styles = css`...``.
-- CSS custom properties cross shadow boundaries.
-- Global/document-level styles do not reach shadow DOM internals.
-- Opting out of Shadow DOM requires `createRenderRoot() { return this; }` — an escape hatch, not a first-class feature.
-
-### Symbiote.js
-
-- **Shadow DOM is opt-in** — Light DOM is the default. Use shadow only where isolation is needed.
-- Two style interfaces: `rootStyles` (Light DOM, adopted stylesheets) and `shadowStyles` (Shadow DOM). Combinable on the same component.
-- **CSS Data Binding** — component state can be initialized directly from CSS custom properties. This enables CSS-driven configuration: themes, layout parameters, localization strings — all without touching JavaScript.
-- **Context from CSS** — the `--ctx` custom property can assign shared context names via the CSS cascade, enabling layout-driven component grouping.
-- The `css` helper function returns `CSSStyleSheet` instances with optional processing pipeline (`css.useProcessor()`).
-
-The opt-in Shadow DOM approach is important for widgets and micro-frontends: it lets embedding applications style components normally when isolation is not desired, while still supporting full encapsulation when it is.
-
-## Loose Coupling and Micro-Frontends
-
-This is where Symbiote.js was specifically designed to excel.
-
-Lit components are standard custom elements and work in any framework, but the library itself doesn't provide special architecture for loose coupling. Template `this`-binding, Shadow DOM by default, and decorator-heavy API create a tightly coupled component model.
-
-Symbiote.js was built for agnostic, loosely coupled systems:
-
-- **Templates decouple data from presentation** — the same component can render entirely different UIs via `use-template`.
-- **Pop-up binding** — child components access parent data through the DOM hierarchy, like CSS cascading. No import dependencies, no prop drilling.
-- **Shared context** — unrelated components cooperate by sharing the same `ctx` name. No wiring, no parent orchestrator.
-- **CSS-driven configuration** — components can be configured purely through CSS, without JavaScript.
-- **Hybrid rendering** — some components can be server-only, some client-only, some isomorphic — in the same application. Data contexts can mirror this: same API shape on server (database-backed) and client (API-backed).
-- **No-JS / Low-code** — components can be fully configured via HTML attributes and CSS, enabling systems where non-developers assemble UIs without writing JavaScript.
-
-## Build Tooling
-
-Both libraries work without a build step and with any standard bundler.
-
-Lit's developer experience leans on TypeScript decorators (`@property()`, `@state()`, `@customElement()`), which benefit from a TypeScript build step. The library itself runs without one, but the idiomatic style assumes a compiler.
-
-Symbiote.js relies on standard JavaScript — ESM imports, class fields, template literals. No decorators, no compiler magic. It supports modern `importmap`-based dependency sharing with CDN imports and works with any common-purpose bundler (esbuild, Rollup, etc.) when needed.
-
-## Built-in Routing
-
-Lit does not include a router. Third-party solutions or custom implementations are needed.
-
-Symbiote.js ships with `AppRouter` — a built-in SPA router (optional import) with:
-- Path-based routes with `:param` extraction
-- Route guards (`beforeRoute()`)
-- Lazy loading (`load: () => import(...)`)
-- SSR-safe (creates PubSub context on server, browser APIs skipped automatically)
-- Dynamic i18n-ready titles
-
-## Summary
-
-| Aspect | Symbiote.js | Lit |
-|--------|-------------|-----|
-| **Templates** | Context-free HTML strings, multiple sources, loose coupling | JS-bound tagged templates, tied to `this` |
-| **SSR** | Built-in, zero mismatches, streaming, isomorphic mode | Experimental, 3 packages, load-order constraints, mismatch risk |
-| **State** | Built-in layered contexts (local, pop-up, shared, named, CSS, computed) | Reactive properties + `@lit/context` (separate package) + external libs |
-| **Shadow DOM** | Opt-in | Default |
-| **Styling** | `rootStyles` + `shadowStyles` + CSS Data Binding | Shadow-scoped `static styles` |
-| **Routing** | Built-in `AppRouter` | None |
-| **Bundle** | ~7.3 kb core, ~11.0 kb full | ~5.1 kb core + addons |
-| **Architecture** | Loose coupling, micro-frontends, no-JS config | Component-first, decorator-driven |
-| **Ecosystem** | Smaller community, focused tooling (JSDA-Kit) | Large community, Google-backed, mature ecosystem |
-
-Lit is a mature, well-supported library with a large community and strong ecosystem. It's a solid choice for teams that want a lightweight framework experience with custom elements.
-
-Symbiote.js is designed for a different set of priorities: maximally loose coupling, template flexibility, built-in state management, and seamless isomorphic rendering — all without external dependencies. If you're building widgets, micro-frontends, or framework-agnostic component libraries, these architectural choices make a practical difference.
-
-And since both Lit and Symbiote.js produce standard custom elements, they can coexist on the same page — alongside raw native web components — without conflicts. You don't have to choose one exclusively; mix them freely within a single project, using each where it fits best.
-
----
-
-See also: [Symbiote.js documentation](./README.md) · [SSR guide](./ssr.md) · [Context system](./context.md)