@symbiotejs/symbiote 3.6.0 → 3.8.0-webmcp.1

package/AI_REFERENCE.md

@@ -1,7 +1,7 @@
 # Symbiote.js — AI Context Reference (v3.x)
 
 > **Purpose**: Authoritative reference for AI code assistants. All information is derived from source code analysis of [symbiote.js](https://github.com/symbiotejs/symbiote.js).
-> Current version: **3.4.7**. Zero dependencies. ~6.4 KB brotli / ~7.1 KB gzip.
+> Current version: **3.8.0**. Zero dependencies. ~7.3 KB brotli / ~8.1 KB gzip.
 
 ---
 
@@ -18,6 +18,7 @@ import Symbiote, { html, css } from 'https://esm.run/@symbiotejs/symbiote';
 import Symbiote from '@symbiotejs/symbiote/core/Symbiote.js';
 import { PubSub } from '@symbiotejs/symbiote/core/PubSub.js';
 import { AppRouter } from '@symbiotejs/symbiote/core/AppRouter.js';
+import { ToolDescriptor } from '@symbiotejs/symbiote/webmcp';
 import { html } from '@symbiotejs/symbiote/core/html.js';
 import { css } from '@symbiotejs/symbiote/core/css.js';
 ```
@@ -25,6 +26,9 @@ import { css } from '@symbiotejs/symbiote/core/css.js';
 ### Core exports (index.js)
 `Symbiote` (default), `html`, `css`, `PubSub`, `DICT`, `animateOut`
 
+### WebMCP experimental exports (`@symbiotejs/symbiote/webmcp`)
+`ToolDescriptor`, `installWebMCP`, `webMCPRegistry`, `syncWebMCPTools`, `unregisterWebMCPTools`, `getActiveWebMCPTools`
+
 ### Utils exports (`@symbiotejs/symbiote/utils`)
 `UID`, `setNestedProp`, `applyStyles`, `applyAttributes`, `create`, `kebabToCamel`, `reassignDictionary`
 
@@ -267,6 +271,57 @@ ctx.multiPub({ score: 100, userName: 'Hero' });
 
 ---
 
+## WebMCP Tools (Experimental)
+
+Install the experimental npm release with:
+```shell
+npm i @symbiotejs/symbiote@webmcp
+```
+
+WebMCP is optional and must be imported before participating components render:
+```js
+import Symbiote, { html } from '@symbiotejs/symbiote';
+import { ToolDescriptor } from '@symbiotejs/symbiote/webmcp';
+```
+
+Automatic mode creates tools from bound event handlers:
+```js
+Symbiote.mcpToolMode = true;
+
+class MyCounter extends Symbiote {
+  count = 0;
+  incrementCount() { this.$.count++; }
+}
+
+MyCounter.template = html`
+  <button ${{onclick: 'incrementCount'}}>Increment</button>
+`;
+MyCounter.reg('my-counter');
+```
+
+Generated names preserve the handler key and custom element tag, e.g. `incrementCount_in_my-counter`. Itemized component tools include `_KEY_` when available, and popup `^handler` bindings can create ancestor-owned tools with source item context.
+
+Use `ToolDescriptor` for descriptions, schemas, execution, and dynamic visibility:
+```js
+init$ = {
+  canRun: false,
+  run_tool: new ToolDescriptor({
+    description: 'Run the visible action.',
+    deps: ['canRun'],
+    when: () => this.$.canRun,
+    inputSchema: {
+      type: 'object',
+      properties: { amount: { type: 'number' } },
+    },
+    execute: ({ amount = 1 }) => this.run(amount),
+  }),
+};
+```
+
+`when()` is not auto-tracked; declare `deps` explicitly. Components may provide `componentDescription` as a string or async function to append more context to component-owned tool descriptions. Native testing requires a browser with WebMCP support, such as Chrome Canary 150.
+
+---
+
 ## Shared Context (`*` prefix)
 
 Components grouped by the `ctx` HTML attribute (or `--ctx` CSS custom property) share a data context. Properties with `*` prefix are read/written in this shared context — inspired by native HTML `name` attribute grouping (like radio button groups):

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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.5.4
 
 ### Fixed

package/README.md

@@ -1,7 +1,7 @@
 [![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-5.9_kb-blue)
+![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)
 
@@ -9,12 +9,13 @@
 
 <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. **~6kb** brotli / **~7kb** gzip.
+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.
 
 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.
 
 ## What's new in v3
 
+- **Experimental WebMCP support** - expose live Symbiote UI actions as browser-native tools for agents. See the [WebMCP docs](./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.
@@ -330,6 +331,7 @@ CSS values are parsed automatically - quoted strings become strings, numbers bec
 ## Best for
 
 - **Complex widgets** embedded in any host application
+- **Low-code HTML-based solutions** - simple declarative everything
 - **Micro frontends** - standard custom elements, no framework coupling
 - **Reusable component libraries** - works in React, Vue, Angular, or plain HTML
 - **SSR-powered apps** - lightweight server rendering without framework lock-in
@@ -339,12 +341,13 @@ CSS values are parsed automatically - quoted strings become strings, numbers bec
 
 | Library | Minified | Gzip | Brotli |
 |---------|----------|------|--------|
-| **Symbiote.js** (core) | 18.9 kb | 6.6 kb | **5.9 kb** |
-| **Symbiote.js** (full, with AppRouter) | 23.2 kb | 7.9 kb | **7.2 kb** |
+| **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 **5.9 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 **~8× larger** before adding a router, state manager, or SSR framework.
+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.
 
 ## Browser support
 
@@ -359,6 +362,13 @@ All modern browsers: Chrome, Firefox, Safari, Edge, Opera.
 - [AI Reference](https://github.com/symbiotejs/symbiote.js/blob/main/AI_REFERENCE.md)
 - [Changelog](https://github.com/symbiotejs/symbiote.js/blob/main/CHANGELOG.md)
 
+## Related articles
+
+- [Symbiote.js: superpowers for Web Components](https://dev.to/foxeyes/symbiotejs-superpowers-for-web-components-1gid)
+- [Symbiote.js: v3 highlights](https://dev.to/foxeyes/symbiotejs-v3-web-components-with-ssr-in-6kb-10n6)
+- [Symbiote.js vs Lit](https://dev.to/foxeyes/lit-vs-symbiotejs-22gj)
+- [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)
+
 **Questions or proposals? Welcome to [Symbiote Discussions](https://github.com/symbiotejs/symbiote.js/discussions)!** ❤️
 
 ---

package/core/PubSub.js

@@ -253,6 +253,7 @@ export class PubSub {
     }
     this.store[prop] = val;
     this.notify(prop, val);
+    globalThis[DICT.MCP_PUBSUB_CHANGED_KEY]?.(this, prop);
   }
 
   /**
@@ -274,6 +275,7 @@ export class PubSub {
     }
     this.store[prop] = val;
     this.notify(prop, val);
+    globalThis[DICT.MCP_PUBSUB_CHANGED_KEY]?.(this, prop);
   }
 
   /** @returns {T} */
@@ -300,6 +302,17 @@ export class PubSub {
     }
   }
 
+  /** @param {keyof T} prop */
+  delete(prop) {
+    if (!this.#storeIsProxy && !(prop in this.store)) {
+      PubSub.#warn('delete', prop, this);
+      return;
+    }
+    delete this.store[prop];
+    this.notify(prop, null);
+    globalThis[DICT.MCP_PUBSUB_CHANGED_KEY]?.(this, prop);
+  }
+
   /** @param {keyof T} prop */
   notify(prop, val) {
     // @ts-expect-error
@@ -386,11 +399,14 @@ export class PubSub {
         }
       }
     }
+    globalThis[DICT.MCP_PUBSUB_REGISTERED_KEY]?.(data, uid);
     return data;
   }
 
   /** @param {String | Symbol} uid */
   static deleteCtx(uid) {
+    let ctx = PubSub.globalStore.get(uid);
+    ctx && globalThis[DICT.MCP_PUBSUB_DELETED_KEY]?.(ctx, uid);
     PubSub.globalStore.delete(uid);
   }
 

package/core/Symbiote.js

@@ -4,6 +4,7 @@ import { DICT } from './dictionary.js';
 import { animateOut } from './animateOut.js';
 import { setNestedProp } from '../utils/setNestedProp.js';
 import { prepareStyleSheet } from '../utils/prepareStyleSheet.js';
+import { parseProp } from './parseProp.js';
 
 import PROCESSORS from './tpl-processors.js';
 import { parseCssPropertyValue } from '../utils/parseCssPropertyValue.js';
@@ -45,6 +46,15 @@ export class Symbiote extends HTMLElement {
   /** @type {HTMLTemplateElement} */
   static __tpl;
 
+  /** @type {Boolean} */
+  static mcpToolMode = false;
+
+  /** @type {string | (() => string | Promise<string>)} */
+  static componentDescription;
+
+  /** @type {string | (() => string | Promise<string>)} */
+  componentDescription;
+
   static set devMode(val) {
     devState.devMode = val;
   }
@@ -76,6 +86,7 @@ export class Symbiote extends HTMLElement {
    * @param {Boolean} [shadow]
    */
   render(template, shadow = this.renderShadow) {
+    this[DICT.MCP_EVENTS_KEY] = [];
     /** @type {DocumentFragment} */
     let fr;
     if ((shadow || this.#super.shadowStyleSheets) && !this.shadowRoot) {
@@ -150,6 +161,7 @@ export class Symbiote extends HTMLElement {
       } catch (e) {
         if (!globalThis.__SYMBIOTE_SSR) throw e;
       }
+      this.syncWebMCPTools?.();
     };
 
     if (this.#super.shadowStyleSheets) {
@@ -192,6 +204,21 @@ export class Symbiote extends HTMLElement {
     this.allowTemplateInits = true;
     /** @type {Boolean} */
     this.lazyMode = false;
+    /** @type {Boolean} */
+    this.mcpToolMode = false;
+  }
+
+  syncWebMCPTools() {
+    if (globalThis.__SYMBIOTE_SSR) return;
+    let sync = globalThis[DICT.MCP_SYNC_OWNER_KEY];
+    if (sync) {
+      sync(this);
+    }
+  }
+
+  unregisterWebMCPTools() {
+    if (globalThis.__SYMBIOTE_SSR) return;
+    globalThis[DICT.MCP_UNREGISTER_OWNER_KEY]?.(this);
   }
 
   /** @returns {String} */
@@ -228,47 +255,10 @@ export class Symbiote extends HTMLElement {
    * @template {Symbiote} T
    * @param {String} prop
    * @param {T} fnCtx
+   * @returns {import('./parseProp.js').ParsedProp | null}
    */
-  static #parseProp(prop, fnCtx) {
-    /** @type {PubSub} */
-    let ctx;
-    /** @type {String} */
-    let name;
-    let first = prop.charCodeAt(0);
-    // Fast path for common local props (no prefix, no /)
-    // Char codes: * = 42, ^ = 94, @ = 64, + = 43, - = 45
-    if (first !== 42 && first !== 94 && first !== 64 && first !== 43 && first !== 45 && !prop.includes('/')) {
-      return { ctx: fnCtx.localCtx, name: prop };
-    }
-    if (first === 42) {
-      ctx = fnCtx.sharedCtx;
-      name = prop.slice(1);
-    } else if (first === 94) {
-      name = prop.slice(1);
-      let found = fnCtx;
-      while (found && !found?.has?.(name)) {
-        // @ts-expect-error
-        found = found.parentElement || found.parentNode || found.host;
-      }
-      ctx = found?.localCtx || fnCtx.localCtx;
-    } else if (prop.includes('/')) {
-      let slashIdx = prop.indexOf('/');
-      ctx = PubSub.getCtx(prop.slice(0, slashIdx), false);
-      if (!ctx) {
-        return null;
-      }
-      name = prop.slice(slashIdx + 1);
-    } else if (first === 45 && prop.charCodeAt(1) === 45) {
-      ctx = fnCtx.localCtx;
-      name = prop;
-      if (!ctx.has(name)) {
-        fnCtx.bindCssData(name);
-      }
-    } else {
-      ctx = fnCtx.localCtx;
-      name = prop;
-    }
-    return { ctx, name };
+  static parseProp(prop, fnCtx) {
+    return parseProp(prop, fnCtx);
   }
 
   /**
@@ -284,7 +274,7 @@ export class Symbiote extends HTMLElement {
       }
       handler(val);
     };
-    let parsed = Symbiote.#parseProp(/** @type {string} */ (prop), this);
+    let parsed = Symbiote.parseProp(/** @type {string} */ (prop), this);
     if (!parsed) {
       // Named context not found — defer subscription
       let slashIdx = /** @type {string} */ (prop).indexOf('/');
@@ -317,14 +307,14 @@ export class Symbiote extends HTMLElement {
 
   /** @param {String} prop */
   notify(prop) {
-    let parsed = Symbiote.#parseProp(prop, this);
+    let parsed = Symbiote.parseProp(prop, this);
     if (!parsed) return;
     parsed.ctx.notify(parsed.name);
   }
 
   /** @param {String} prop */
   has(prop) {
-    let parsed = Symbiote.#parseProp(prop, this);
+    let parsed = Symbiote.parseProp(prop, this);
     if (!parsed) return false;
     return parsed.ctx.has(parsed.name);
   }
@@ -336,7 +326,7 @@ export class Symbiote extends HTMLElement {
    * @param {Boolean} [rewrite]
    */
   add(prop, val, rewrite = false) {
-    let parsed = Symbiote.#parseProp(prop, this);
+    let parsed = Symbiote.parseProp(prop, this);
     if (!parsed) return;
     parsed.ctx.add(parsed.name, val, rewrite);
   }
@@ -362,9 +352,9 @@ export class Symbiote extends HTMLElement {
           if (first !== 42 && first !== 94 && first !== 64 && first !== 43 && first !== 45 && !prop.includes('/')) {
             this.localCtx.pub(prop, val);
           } else {
-          let parsed = Symbiote.#parseProp(prop, this);
-          if (!parsed) return true;
-          parsed.ctx.pub(parsed.name, val);
+            let parsed = Symbiote.parseProp(prop, this);
+            if (!parsed) return true;
+            parsed.ctx.pub(parsed.name, val);
           }
           return true;
         },
@@ -373,7 +363,7 @@ export class Symbiote extends HTMLElement {
           if (first !== 42 && first !== 94 && first !== 64 && first !== 43 && first !== 45 && !prop.includes('/')) {
             return this.localCtx.read(prop);
           }
-          let parsed = Symbiote.#parseProp(prop, this);
+          let parsed = Symbiote.parseProp(prop, this);
           if (!parsed) return undefined;
           return parsed.ctx.read(parsed.name);
         },
@@ -516,6 +506,8 @@ export class Symbiote extends HTMLElement {
         }
         this.render();
       }
+    } else {
+      this.syncWebMCPTools?.();
     }
     this.connectedOnce = true;
   }
@@ -589,6 +581,7 @@ export class Symbiote extends HTMLElement {
     if (!this.connectedOnce) {
       return;
     }
+    this.unregisterWebMCPTools();
     this.dropCssDataCache();
     if (!this.readyToDestroy) {
       return;

package/core/dictionary.js

@@ -37,4 +37,26 @@ export const DICT = {
   TEXT_NODE_OPEN_TOKEN: '{{',
   // Text node binding token:
   TEXT_NODE_CLOSE_TOKEN: '}}',
+  // WebMCP component event handler metadata key:
+  MCP_EVENTS_KEY: '__symbioteMcpEventHandlers',
+  // WebMCP ToolDescriptor marker key:
+  MCP_TOOL_DESCRIPTOR_MARKER: '__symbioteToolDescriptor',
+  // WebMCP owner id metadata key:
+  MCP_OWNER_ID_KEY: '__symbioteMcpOwnerId',
+  // WebMCP global hook for owner sync:
+  MCP_SYNC_OWNER_KEY: '__SYMBIOTE_WEBMCP_SYNC_OWNER',
+  // WebMCP global hook for owner cleanup:
+  MCP_UNREGISTER_OWNER_KEY: '__SYMBIOTE_WEBMCP_UNREGISTER_OWNER',
+  // WebMCP global hook for PubSub context registration:
+  MCP_PUBSUB_REGISTERED_KEY: '__SYMBIOTE_WEBMCP_PUBSUB_REGISTERED',
+  // WebMCP global hook for PubSub context deletion:
+  MCP_PUBSUB_DELETED_KEY: '__SYMBIOTE_WEBMCP_PUBSUB_DELETED',
+  // WebMCP global hook for PubSub property changes:
+  MCP_PUBSUB_CHANGED_KEY: '__SYMBIOTE_WEBMCP_PUBSUB_CHANGED',
+  // WebMCP itemize item visible index metadata key:
+  MCP_ITEM_INDEX_KEY: '__symbioteMcpItemIndex',
+  // WebMCP itemize item stable key metadata key:
+  MCP_ITEM_KEY_KEY: '__symbioteMcpItemKey',
+  // WebMCP forwarded event target owners metadata key:
+  MCP_EVENT_TARGET_OWNERS_KEY: '__symbioteMcpEventTargetOwners',
 };

package/core/full.js

@@ -1,2 +1,3 @@
 export { default, Symbiote, html, css, PubSub, DICT, animateOut } from './index.js';
 export { AppRouter } from './AppRouter.js';
+export { ToolDescriptor } from './webmcp.js';

package/core/html.js

@@ -10,6 +10,35 @@ export const RESERVED_ATTRIBUTES = [
   DICT.CTX_NAME_ATTR,
 ];
 
+const RESERVED_ATTRIBUTES_SET = new Set(RESERVED_ATTRIBUTES);
+const SELF_CLOSING_CUSTOM_ELEMENT_RE = /<([a-z][.0-9_a-z]*-[\-.0-9_a-z]*)(\s+(?:"[^"]*"|'[^']*'|[^'"<>])*)?\/>/gi;
+
+function hasImmediateClosingTag(htmlString, startIdx, tagName) {
+  let idx = startIdx;
+  let len = htmlString.length;
+  while (idx < len) {
+    let code = htmlString.charCodeAt(idx);
+    if (code !== 32 && code !== 9 && code !== 10 && code !== 12 && code !== 13) break;
+    idx++;
+  }
+  if (htmlString.charCodeAt(idx) !== 60 || htmlString.charCodeAt(idx + 1) !== 47) return false;
+  let tagStart = idx + 2;
+  if (htmlString.charCodeAt(tagStart + tagName.length) !== 62) return false;
+  let closingTagName = htmlString.slice(tagStart, tagStart + tagName.length);
+  return closingTagName === tagName || closingTagName.toLowerCase() === tagName.toLowerCase();
+}
+
+function closeSelfClosingCustomElements(resultHtml) {
+  if (resultHtml.indexOf('/>') === -1) return resultHtml;
+  return resultHtml.replace(SELF_CLOSING_CUSTOM_ELEMENT_RE, (match, tagName, attrs = '', offset, htmlString) => {
+    let openTag = `<${tagName}${attrs && attrs.trimEnd()}>`;
+    if (hasImmediateClosingTag(htmlString, offset + match.length, tagName)) {
+      return openTag;
+    }
+    return `${openTag}</${tagName}>`;
+  });
+}
+
 /** @typedef {Record<keyof import('./Symbiote.js').Symbiote, String>} BindDescriptor */
 
 /**
@@ -20,19 +49,20 @@ export const RESERVED_ATTRIBUTES = [
  */
 export function html(parts, ...props) {
   let resultHtml = '';
-  parts.forEach((part, idx) => {
-    resultHtml += part;
-    if (idx >= props.length) return;
+  let propsLength = props.length;
+  for (let idx = 0; idx < parts.length; idx++) {
+    resultHtml += parts[idx];
+    if (idx >= propsLength) continue;
     let val = props[idx];
     if (val === undefined || val === null) {
       errMsg(15, val);
-      return;
+      continue;
     }
-    if (val?.constructor === Object) {
+    if (val.constructor === Object) {
       let bindStr = '';
       // @ts-expect-error
       for (let key in val) {
-        if (RESERVED_ATTRIBUTES.includes(key)) {
+        if (RESERVED_ATTRIBUTES_SET.has(key)) {
           resultHtml += ` ${key}="${val[key]}"`;
         } else {
           bindStr += `${key}:${val[key]};`;
@@ -42,8 +72,8 @@ export function html(parts, ...props) {
     } else {
       resultHtml += val;
     }
-  });
-  return resultHtml;
+  }
+  return closeSelfClosingCustomElements(resultHtml);
 }
 
 export default html;

package/core/itemizeProcessor.js

@@ -1,6 +1,17 @@
 import { animateOut } from './animateOut.js';
 import { warnMsg } from './warn.js';
 import { setupItemize } from './itemizeSetup.js';
+import { DICT } from './dictionary.js';
+
+function setItemWebMCPMetadata(itemEl, item, idx) {
+  if (!itemEl) return;
+  itemEl[DICT.MCP_ITEM_INDEX_KEY] = idx;
+  if (item && Object.prototype.hasOwnProperty.call(item, '_KEY_')) {
+    itemEl[DICT.MCP_ITEM_KEY_KEY] = item._KEY_;
+  } else {
+    delete itemEl[DICT.MCP_ITEM_KEY_KEY];
+  }
+}
 
 /**
  * @template {import('./Symbiote.js').Symbiote} T
@@ -22,6 +33,7 @@ export function itemizeProcessor(fr, fnCtx) {
       let fillItems = (/** @type {*[]} */ items) => {
         items.forEach((item, idx) => {
           if (currentList[idx]) {
+            setItemWebMCPMetadata(currentList[idx], item, idx);
             if (currentList[idx].set$) {
               currentList[idx].set$(item);
             } else {
@@ -37,6 +49,7 @@ export function itemizeProcessor(fr, fnCtx) {
             if (isLazy) {
               repeatItem.lazyMode = true;
             }
+            setItemWebMCPMetadata(repeatItem, item, idx);
             Object.assign((repeatItem?.init$ || repeatItem), item);
             fragment.appendChild(repeatItem);
           }

package/core/parseProp.js

@@ -0,0 +1,87 @@
+import PubSub from './PubSub.js';
+import { DICT } from './dictionary.js';
+
+const BINDING_PREFIXES = [
+  DICT.SHARED_CTX_PX,
+  DICT.PARENT_CTX_PX,
+  DICT.ATTR_BIND_PX,
+  DICT.COMPUTED_PX,
+  DICT.CSS_DATA_PX,
+];
+
+/** @param {string} propStr */
+function hasBindingPrefix(propStr) {
+  for (let prefix of BINDING_PREFIXES) {
+    if (propStr.startsWith(prefix)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * @typedef {Object} ParsedProp
+ * @property {PubSub} ctx
+ * @property {string} name
+ * @property {'local' | 'parent' | 'shared' | 'named' | 'css-data'} scope
+ * @property {string} [ctxName]
+ * @property {any} [owner]
+ */
+
+/**
+ * Resolve a Symbiote binding token to its PubSub context and property name.
+ *
+ * @template {import('./Symbiote.js').Symbiote} T
+ * @param {String} prop
+ * @param {T} fnCtx
+ * @returns {ParsedProp | null}
+ */
+export function parseProp(prop, fnCtx) {
+  /** @type {PubSub} */
+  let ctx;
+  /** @type {String} */
+  let name;
+  let propStr = String(prop);
+  // Fast path for common local props (no prefix, no /)
+  if (!hasBindingPrefix(propStr) && !propStr.includes(DICT.NAMED_CTX_SPLTR)) {
+    return { ctx: fnCtx.localCtx, name: propStr, scope: 'local', owner: fnCtx };
+  }
+  if (propStr.startsWith(DICT.SHARED_CTX_PX)) {
+    ctx = fnCtx.sharedCtx;
+    name = propStr.slice(DICT.SHARED_CTX_PX.length);
+    return { ctx, name, scope: 'shared', ctxName: fnCtx.ctxName };
+  }
+  if (propStr.startsWith(DICT.PARENT_CTX_PX)) {
+    name = propStr.slice(DICT.PARENT_CTX_PX.length);
+    let found = fnCtx;
+    while (found && !found?.has?.(name)) {
+      // @ts-expect-error
+      found = found.parentElement || found.parentNode || found.host;
+    }
+    ctx = found?.localCtx || fnCtx.localCtx;
+    return { ctx, name, scope: 'parent', owner: found || fnCtx };
+  }
+  if (propStr.includes(DICT.NAMED_CTX_SPLTR)) {
+    let slashIdx = propStr.indexOf(DICT.NAMED_CTX_SPLTR);
+    let ctxName = propStr.slice(0, slashIdx);
+    ctx = PubSub.getCtx(ctxName, false);
+    if (!ctx) {
+      return null;
+    }
+    name = propStr.slice(slashIdx + 1);
+    return { ctx, name, scope: 'named', ctxName };
+  }
+  if (propStr.startsWith(DICT.CSS_DATA_PX)) {
+    ctx = fnCtx.localCtx;
+    name = propStr;
+    if (!ctx.has(name)) {
+      fnCtx.bindCssData(name);
+    }
+    return { ctx, name, scope: 'css-data', owner: fnCtx };
+  }
+  ctx = fnCtx.localCtx;
+  name = propStr;
+  return { ctx, name, scope: 'local', owner: fnCtx };
+}
+
+export default parseProp;