@symbiotejs/symbiote 3.10.1 → 3.10.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/core/PubSub.js +18 -5
  2. package/core/Symbiote.js +9 -5
  3. package/core/dictionary.js +5 -22
  4. package/core/extensions.js +17 -0
  5. package/core/itemizeProcessor-keyed.js +2 -2
  6. package/core/itemizeProcessor.js +3 -3
  7. package/core/itemizeSetup.js +4 -4
  8. package/core/ownElements.js +3 -3
  9. package/core/tpl-processors.js +20 -92
  10. package/core/webmcp-bindings.js +59 -0
  11. package/core/webmcp-dictionary.js +17 -0
  12. package/core/webmcp.js +216 -51
  13. package/docs/webmcp.md +80 -0
  14. package/html-app/BaseClass.js +2 -2
  15. package/html-app/README.md +16 -1
  16. package/html-app/actions.js +4 -2
  17. package/html-app/collection-items.js +1 -1
  18. package/html-app/examples/assets/actions.html +10 -10
  19. package/html-app/examples/assets/collections.html +19 -19
  20. package/html-app/examples/assets/components.html +1 -1
  21. package/html-app/examples/assets/conditional.html +2 -2
  22. package/html-app/examples/assets/data.html +5 -5
  23. package/html-app/examples/assets/guide.html +1 -1
  24. package/html-app/examples/assets/not-found.html +1 -1
  25. package/html-app/examples/assets/routing.html +2 -2
  26. package/html-app/examples/assets/state.html +2 -2
  27. package/html-app/examples/assets/storage.html +6 -6
  28. package/html-app/examples/full-app.html +3 -2
  29. package/html-app/sym-conditional.js +1 -1
  30. package/package.json +13 -1
  31. package/scripts/check-html-app-size.js +2 -0
  32. package/skills/symbiote/SKILL.md +24 -1
  33. package/types/core/PubSub.d.ts.map +1 -1
  34. package/types/core/Symbiote.d.ts.map +1 -1
  35. package/types/core/dictionary.d.ts +3 -11
  36. package/types/core/extensions.d.ts +13 -0
  37. package/types/core/extensions.d.ts.map +1 -0
  38. package/types/core/itemizeSetup.d.ts +1 -1
  39. package/types/core/itemizeSetup.d.ts.map +1 -1
  40. package/types/core/tpl-processors.d.ts +0 -7
  41. package/types/core/tpl-processors.d.ts.map +1 -1
  42. package/types/core/webmcp-bindings.d.ts +18 -0
  43. package/types/core/webmcp-bindings.d.ts.map +1 -0
  44. package/types/core/webmcp-dictionary.d.ts +36 -0
  45. package/types/core/webmcp-dictionary.d.ts.map +1 -0
  46. package/types/core/webmcp.d.ts.map +1 -1
  47. package/types/html-app/actions.d.ts.map +1 -1
  48. package/types/utils/reassignDictionary.d.ts +3 -11
  49. package/types/utils/reassignDictionary.d.ts.map +1 -1
  50. package/types/utils/setNestedProp.d.ts.map +1 -1
  51. package/utils/setNestedProp.js +8 -0
package/core/webmcp.js CHANGED
@@ -3,6 +3,9 @@ import Symbiote from './Symbiote.js';
3
3
  import { devState } from './warn.js';
4
4
  import { DICT } from './dictionary.js';
5
5
  import { parseProp } from './parseProp.js';
6
+ import { extensions } from './extensions.js';
7
+ import { WEBMCP_DICT as MCP } from './webmcp-dictionary.js';
8
+ import { isToolDescriptor, webMCPBindings } from './webmcp-bindings.js';
6
9
 
7
10
  /**
8
11
  * @typedef {Object} WebMCPToolResultText
@@ -58,10 +61,6 @@ let pendingOwnerSync = new WeakSet();
58
61
  let ownerVersions = new WeakMap();
59
62
  let _modelContext;
60
63
 
61
- function isToolDescriptor(val) {
62
- return !!val?.[DICT.MCP_TOOL_DESCRIPTOR_MARKER];
63
- }
64
-
65
64
  function isElementOwner(owner) {
66
65
  return typeof HTMLElement !== 'undefined' && owner instanceof HTMLElement;
67
66
  }
@@ -173,7 +172,7 @@ function ownerToolName(owner) {
173
172
  if (!isElementOwner(owner)) {
174
173
  return name;
175
174
  }
176
- let identity = owner[DICT.MCP_ITEM_KEY_KEY] ?? owner[DICT.MCP_ITEM_INDEX_KEY];
175
+ let identity = owner[DICT.ITEM_KEY_KEY] ?? owner[DICT.ITEM_INDEX_KEY];
177
176
  let clean = identity === undefined ? '' : cleanIdentity(identity);
178
177
  return clean ? `${name}_${clean}` : name;
179
178
  }
@@ -264,10 +263,10 @@ function ownerType(owner) {
264
263
  }
265
264
 
266
265
  function ownerId(owner) {
267
- if (!owner[DICT.MCP_OWNER_ID_KEY]) {
268
- owner[DICT.MCP_OWNER_ID_KEY] = `${ownerType(owner)}-${++ownerIdCount}`;
266
+ if (!owner[MCP.OWNER_ID_KEY]) {
267
+ owner[MCP.OWNER_ID_KEY] = `${ownerType(owner)}-${++ownerIdCount}`;
269
268
  }
270
- return owner[DICT.MCP_OWNER_ID_KEY];
269
+ return owner[MCP.OWNER_ID_KEY];
271
270
  }
272
271
 
273
272
  function getModelContext() {
@@ -428,6 +427,7 @@ function makeEntryWithComponentDescription(publicName, key, descriptor, owner, e
428
427
  let schema = readInputSchema(descriptor, owner);
429
428
  let entry = {
430
429
  name: publicName,
430
+ baseName: publicName,
431
431
  key,
432
432
  ownerId: id,
433
433
  ownerType: ownerType(owner),
@@ -475,18 +475,173 @@ function createExplicitDesired(owner, key, descriptor) {
475
475
  };
476
476
  }
477
477
 
478
- function createAutoDesired(owner, key, eventBinding = null) {
478
+ function normalizeText(value) {
479
+ return String(value ?? '').replace(/\s+/g, ' ').trim();
480
+ }
481
+
482
+ function textAttribute(el, name) {
483
+ return normalizeText(el?.getAttribute?.(name));
484
+ }
485
+
486
+ function controlLabel(el) {
487
+ let root = el?.getRootNode?.() || el?.ownerDocument;
488
+ let references = textAttribute(el, 'aria-labelledby').split(' ').filter(Boolean);
489
+ let label = references.map((id) => root?.getElementById?.(id)?.textContent || '').join(' ');
490
+ label = normalizeText(label) || textAttribute(el, 'aria-label');
491
+ if (!label) {
492
+ label = normalizeText(Array.from(el?.labels || [], (label) => {
493
+ let content = label.cloneNode(true);
494
+ content.querySelectorAll('input, textarea, select, button, meter, output, progress').forEach((control) => control.remove());
495
+ return content.textContent;
496
+ }).join(' '));
497
+ }
498
+ if (!label && (['button', 'a'].includes(el?.localName) || textAttribute(el, 'role') === 'button')) {
499
+ label = normalizeText(el.textContent);
500
+ }
501
+ if (!label && el?.localName === 'input' && ['button', 'submit', 'reset'].includes(el.type)) {
502
+ label = normalizeText(el.value);
503
+ }
504
+ label ||= textAttribute(el, 'title');
505
+ return label.length > 200 ? `${label.slice(0, 199)}…` : label;
506
+ }
507
+
508
+ function submissionForm(owner, binding) {
509
+ let el = binding.el;
510
+ if (binding.prop === 'onsubmit' && el?.localName === 'form') {
511
+ return el;
512
+ }
513
+ // A separately bound submit control duplicates the form only when it uses
514
+ // the same handler. Independent click operations keep their own tools.
515
+ if (binding.prop === 'onclick' && ['button', 'input'].includes(el?.localName)
516
+ && ['submit', 'image'].includes(el.type) && el.form?.onsubmit === owner.$?.[binding.key]) {
517
+ return el.form;
518
+ }
519
+ return null;
520
+ }
521
+
522
+ function hasNativeFormTools(form) {
523
+ let doc = form.ownerDocument;
524
+ let prototype = doc?.defaultView?.SubmitEvent?.prototype;
525
+ // SubmitEvent's WebMCP extensions are gated by declarative support,
526
+ // independently of the imperative modelContext API.
527
+ return !!(doc?.modelContext?.registerTool && prototype
528
+ && 'agentInvoked' in prototype && typeof prototype.respondWith === 'function');
529
+ }
530
+
531
+ function autoBindingAvailable(owner, binding) {
532
+ let el = binding.el;
533
+ if (!Object.hasOwn(MCP.TOOL_EVENTS, binding.prop) || el?.isConnected === false
534
+ || binding.sourceOwner?.isConnected === false) {
535
+ return false;
536
+ }
537
+ let form = submissionForm(owner, binding);
538
+ if (form && textAttribute(form, MCP.TOOL_NAME_ATTR) && textAttribute(form, MCP.TOOL_DESCRIPTION_ATTR)) {
539
+ if (hasNativeFormTools(form) || !form.hasAttribute(MCP.TOOL_AUTOSUBMIT_ATTR)) {
540
+ return false;
541
+ }
542
+ }
543
+ if (binding.prop === 'oninput' || binding.prop === 'onchange') {
544
+ return !el?.matches?.(':disabled') && !el?.readOnly && !el?.closest?.('[inert], [aria-disabled="true"]');
545
+ }
546
+ return true;
547
+ }
548
+
549
+ function autoControlInput(el, prop) {
550
+ let editing = prop === 'oninput' || prop === 'onchange';
551
+ let supported = ['input', 'textarea', 'select'].includes(el?.localName);
552
+ if (!editing || !supported) {
553
+ return prop === 'oninput' ? null : { inputSchema: emptySchema(), apply() {} };
554
+ }
555
+ if (el.localName === 'input' && ['file', 'hidden', 'button', 'submit', 'reset', 'image'].includes(el.type)) {
556
+ return null;
557
+ }
558
+ let checked = el.localName === 'input' && ['checkbox', 'radio'].includes(el.type);
559
+ let multiple = el.localName === 'select' && el.multiple;
560
+ let numeric = el.localName === 'input' && ['number', 'range'].includes(el.type);
561
+ let property = checked ? 'checked' : 'value';
562
+ let type = checked ? 'boolean' : multiple ? 'array' : numeric ? ['string', 'number'] : 'string';
563
+ let field = { type, description: checked ? 'Checked state to apply to the control.' : 'Value to insert into the control.' };
564
+ let options = el.localName === 'select'
565
+ ? Array.from(el.options).filter((option) => !option.disabled && !option.parentElement?.disabled).map((option) => option.value)
566
+ : null;
567
+ let valueSchema = multiple ? { ...field, items: { type: 'string', enum: options } }
568
+ : options ? { ...field, enum: options } : field;
569
+ return {
570
+ inputSchema: {
571
+ ...emptySchema(),
572
+ properties: { [property]: valueSchema },
573
+ required: prop === 'oninput' ? [property] : [],
574
+ },
575
+ apply(args) {
576
+ if (!Object.hasOwn(args, property)) {
577
+ if (prop === 'oninput') {
578
+ throw new TypeError(`Input tool requires "${property}".`);
579
+ }
580
+ return;
581
+ }
582
+ let value = args[property];
583
+ let valid = checked ? typeof value === 'boolean'
584
+ : multiple ? Array.isArray(value) && value.every((item) => typeof item === 'string')
585
+ : typeof value === 'string' || (numeric && typeof value === 'number' && Number.isFinite(value));
586
+ if (!valid) {
587
+ throw new TypeError(`Invalid control "${property}".`);
588
+ }
589
+ // Check current options, since a tool can outlive a change to the select.
590
+ if (options) {
591
+ let allowed = Array.from(el.options).filter((option) => !option.disabled && !option.parentElement?.disabled).map((option) => option.value);
592
+ if (!(multiple ? value : [value]).every((item) => allowed.includes(item))) {
593
+ throw new TypeError('Unknown or disabled select option.');
594
+ }
595
+ }
596
+ if (multiple) {
597
+ for (let option of el.options) {
598
+ option.selected = value.includes(option.value);
599
+ }
600
+ } else {
601
+ let previous = el[property];
602
+ el[property] = checked ? value : String(value);
603
+ if (!checked && el.value !== String(value)) {
604
+ el[property] = previous;
605
+ throw new TypeError('The control cannot accept this value.');
606
+ }
607
+ }
608
+ },
609
+ };
610
+ }
611
+
612
+ function autoMetadata(owner, binding) {
613
+ let el = binding.el;
614
+ let operation = MCP.TOOL_EVENTS[binding.prop];
615
+ let name = textAttribute(el, MCP.TOOL_NAME_ATTR);
616
+ let description = textAttribute(el, MCP.TOOL_DESCRIPTION_ATTR);
617
+ let label = controlLabel(el);
618
+ let handler = owner.$?.[binding.key];
619
+ let authoredKey = !handler?.[DICT.GENERATED_HANDLER_KEY];
620
+ let priority = description ? 4 : label ? 3 : name ? 2 : authoredKey ? 1 : 0;
621
+ let input = autoControlInput(el, binding.prop);
622
+ if (!priority || !input) {
623
+ return null;
624
+ }
625
+ description ||= `${operation.description}: ${label || name || binding.key}.`;
626
+ let control = el?.localName ? ` Control: <${el.localName}>${label ? ` ${JSON.stringify(label)}` : ''}.` : '';
627
+ let id = textAttribute(el, 'id');
628
+ description += `\nEvent: ${operation.event}.${control}${id ? ` ID: ${id}.` : ''} Component: <${ownerToolName(owner)}>.`;
629
+ return { name, description, priority, ...input };
630
+ }
631
+
632
+ function createAutoDesired(owner, key, eventBinding, metadata) {
479
633
  let tagName = ownerName(owner);
480
634
  let toolOwnerName = ownerToolName(owner);
481
635
  let sourceName = sourceToolName(eventBinding?.sourceOwner);
482
636
  let sourceSuffix = sourceName ? `_${sourceName}` : '';
483
- let publicName = `${key}_in_${toolOwnerName}${sourceSuffix}`;
637
+ let publicName = metadata.name || `${key}_in_${toolOwnerName}${sourceSuffix}`;
484
638
  let sourceDescription = sourceName ? ` Source binding: <${sourceName}>.` : '';
485
639
  let descriptor = new ToolDescriptor({
486
640
  name: publicName,
487
- description: `Active UI action "${key}" in <${tagName}>.${sourceDescription}`,
488
- inputSchema: emptySchema(),
489
- execute: () => {
641
+ description: `${metadata.description}${sourceDescription}`,
642
+ inputSchema: metadata.inputSchema,
643
+ when: () => autoBindingAvailable(owner, eventBinding),
644
+ execute: (input) => {
490
645
  let handler = owner.$?.[key];
491
646
  if (isToolDescriptor(handler)) {
492
647
  return handler.execute({}, owner);
@@ -494,6 +649,7 @@ function createAutoDesired(owner, key, eventBinding = null) {
494
649
  if (typeof handler !== 'function') {
495
650
  throw new Error(`Handler "${key}" is not available on <${tagName}>.`);
496
651
  }
652
+ metadata.apply(input);
497
653
  let result = handler.call(owner, syntheticEvent(eventBinding?.el));
498
654
  let respond = (value) => {
499
655
  let suffix = value ? `: ${value}` : '';
@@ -507,6 +663,7 @@ function createAutoDesired(owner, key, eventBinding = null) {
507
663
  return {
508
664
  key: sourceName ? `auto:${key}@${sourceName}` : `auto:${key}`,
509
665
  baseName: publicName,
666
+ priority: metadata.priority,
510
667
  descriptor,
511
668
  executor(input) {
512
669
  return descriptor.execute(input || {}, owner);
@@ -530,17 +687,19 @@ function collectAutoTools(owner, explicitKeys) {
530
687
  if (!isElementOwner(owner) || !(owner.mcpToolMode || owner.constructor?.mcpToolMode)) {
531
688
  return [];
532
689
  }
533
- let handlers = owner[DICT.MCP_EVENTS_KEY] || [];
534
- let result = [];
535
- let seen = new Set();
690
+ let handlers = owner[MCP.EVENTS_KEY] || [];
691
+ let result = new Map();
536
692
  let seenCtx = new Set();
537
693
  for (let item of handlers) {
694
+ if (!autoBindingAvailable(owner, item)) {
695
+ continue;
696
+ }
538
697
  if (item.sourceOwner && (!item.sourceOwner.isConnected || explicitKeys.has(item.key))) {
539
698
  continue;
540
699
  }
541
700
  let sourceName = sourceToolName(item.sourceOwner);
542
701
  let toolKey = sourceName ? `${item.key}@${sourceName}` : item.key;
543
- if (explicitKeys.has(item.key) || seen.has(toolKey)) {
702
+ if (explicitKeys.has(item.key)) {
544
703
  continue;
545
704
  }
546
705
  let parsed = parseProp(item.key, owner);
@@ -550,13 +709,15 @@ function collectAutoTools(owner, explicitKeys) {
550
709
  syncWebMCPTools(parsed.ctx);
551
710
  }
552
711
  }
553
- if (parsed?.scope !== 'local') {
712
+ if (parsed?.scope !== 'local' || typeof owner.$?.[item.key] !== 'function') {
554
713
  continue;
555
714
  }
556
- seen.add(toolKey);
557
- result.push(createAutoDesired(owner, item.key, item));
715
+ let metadata = autoMetadata(owner, item);
716
+ if (metadata && (!result.has(toolKey) || result.get(toolKey).priority < metadata.priority)) {
717
+ result.set(toolKey, createAutoDesired(owner, item.key, item, metadata));
718
+ }
558
719
  }
559
- return result;
720
+ return [...result.values()];
560
721
  }
561
722
 
562
723
  function collectDesiredTools(owner) {
@@ -627,7 +788,7 @@ export class ToolDescriptor {
627
788
 
628
789
  /** @param {ToolDescriptorOptions} options */
629
790
  constructor(options = {}) {
630
- this[DICT.MCP_TOOL_DESCRIPTOR_MARKER] = true;
791
+ this[MCP.TOOL_DESCRIPTOR_MARKER] = true;
631
792
  this.name = options.name;
632
793
  this.description = options.description || 'Symbiote WebMCP tool.';
633
794
  this.inputSchema = options.inputSchema || emptySchema();
@@ -726,11 +887,17 @@ function applyDesiredTools(owner, id, ownerEntry, desired, componentDescription)
726
887
  }
727
888
  continue;
728
889
  }
729
- let publicName = ownerEntry.toolsByKey[item.key] || resolveName(item.baseName, id, item.key);
890
+ let oldName = ownerEntry.toolsByKey[item.key];
891
+ if (oldName && webMCPRegistry.store.tools.read(oldName)?.baseName !== item.baseName) {
892
+ unregisterToolName(oldName);
893
+ oldName = null;
894
+ }
895
+ let publicName = oldName || resolveName(item.baseName, id, item.key);
730
896
  if (hasToolName(publicName)) {
731
897
  unregisterToolName(publicName);
732
898
  }
733
899
  let entry = makeEntryWithComponentDescription(publicName, item.key, item.descriptor, owner, item.executor, componentDescription);
900
+ entry.baseName = item.baseName;
734
901
  ownerEntry.toolsByKey[item.key] = publicName;
735
902
  webMCPRegistry.store.tools.add(publicName, entry, true);
736
903
  }
@@ -782,11 +949,11 @@ export function syncWebMCPTools(owner) {
782
949
  export function unregisterWebMCPTools(owner) {
783
950
  if (!owner) return;
784
951
  bumpOwnerVersion(owner);
785
- let targets = owner[DICT.MCP_EVENT_TARGET_OWNERS_KEY];
952
+ let targets = owner[MCP.EVENT_TARGET_OWNERS_KEY];
786
953
  if (targets) {
787
954
  for (let target of targets) {
788
- if (target[DICT.MCP_EVENTS_KEY]) {
789
- target[DICT.MCP_EVENTS_KEY] = target[DICT.MCP_EVENTS_KEY].filter((entry) => entry.sourceOwner !== owner);
955
+ if (target[MCP.EVENTS_KEY]) {
956
+ target[MCP.EVENTS_KEY] = target[MCP.EVENTS_KEY].filter((entry) => entry.sourceOwner !== owner);
790
957
  }
791
958
  syncWebMCPTools(target);
792
959
  }
@@ -829,31 +996,29 @@ export function installWebMCP(SymbioteClass = Symbiote) {
829
996
  return;
830
997
  }
831
998
  installedClasses.add(SymbioteClass);
832
- globalThis[DICT.MCP_SYNC_OWNER_KEY] = syncWebMCPTools;
833
- globalThis[DICT.MCP_UNREGISTER_OWNER_KEY] = unregisterWebMCPTools;
834
- globalThis[DICT.MCP_PUBSUB_REGISTERED_KEY] = (ctx, uid) => {
835
- if (uid === REGISTRY_UID) return;
836
- syncWebMCPTools(ctx);
837
- };
838
- globalThis[DICT.MCP_PUBSUB_DELETED_KEY] = (ctx, uid) => {
839
- if (uid === REGISTRY_UID) return;
840
- unregisterWebMCPTools(ctx);
841
- };
842
- globalThis[DICT.MCP_PUBSUB_CHANGED_KEY] = (ctx, prop) => {
843
- if (!ctx.uid || ctx === webMCPRegistry || ctx === webMCPRegistry.store.tools
844
- || ctx === webMCPRegistry.store.owners || ctx === webMCPRegistry.store.diagnostics) {
845
- return;
846
- }
847
- let id = ownerId(ctx);
848
- let existingOwner = webMCPRegistry.store.owners.has(id)
849
- ? webMCPRegistry.store.owners.read(id)
850
- : null;
851
- let propOwnsTool = !!existingOwner?.toolsByKey?.[prop];
852
- if (!isToolDescriptor(ctx.store[prop]) && !propOwnsTool) {
853
- return;
854
- }
855
- syncWebMCPTools(ctx);
856
- };
999
+ globalThis[MCP.SYNC_OWNER_KEY] = syncWebMCPTools;
1000
+ globalThis[MCP.UNREGISTER_OWNER_KEY] = unregisterWebMCPTools;
1001
+ extensions.set('webmcp', {
1002
+ ...webMCPBindings,
1003
+ syncOwner: syncWebMCPTools,
1004
+ disconnectOwner: unregisterWebMCPTools,
1005
+ contextRegistered(ctx, uid) {
1006
+ if (uid !== REGISTRY_UID) syncWebMCPTools(ctx);
1007
+ },
1008
+ contextDeleted(ctx, uid) {
1009
+ if (uid !== REGISTRY_UID) unregisterWebMCPTools(ctx);
1010
+ },
1011
+ contextChanged(ctx, prop) {
1012
+ if (!ctx.uid || ctx === webMCPRegistry || ctx === webMCPRegistry.store.tools
1013
+ || ctx === webMCPRegistry.store.owners || ctx === webMCPRegistry.store.diagnostics) {
1014
+ return;
1015
+ }
1016
+ let existingOwner = webMCPRegistry.store.owners.read(ownerId(ctx));
1017
+ if (isToolDescriptor(ctx.store[prop]) || existingOwner?.toolsByKey?.[prop]) {
1018
+ syncWebMCPTools(ctx);
1019
+ }
1020
+ },
1021
+ });
857
1022
  }
858
1023
 
859
1024
  installWebMCP(Symbiote);
package/docs/webmcp.md CHANGED
@@ -11,6 +11,8 @@ import Symbiote, { html } from '@symbiotejs/symbiote';
11
11
  import '@symbiotejs/symbiote/webmcp';
12
12
  ```
13
13
 
14
+ The operation dictionary and WebMCP binding processors load with this extension. The core entry does not import them; its generic extension hooks also handle component and context lifecycle notifications.
15
+
14
16
  ## Automatic Tools
15
17
 
16
18
  Enable `mcpToolMode` globally or per component to generate tools from bound event handlers:
@@ -35,6 +37,17 @@ WebmcpCounter.template = html`
35
37
  WebmcpCounter.reg('webmcp-counter');
36
38
  ```
37
39
 
40
+ Automatic discovery uses an operation dictionary:
41
+
42
+ | Binding | Operation |
43
+ | --- | --- |
44
+ | `onclick` | Activate a control |
45
+ | `onsubmit` | Submit a form |
46
+ | `onchange` | Commit a control value or selection |
47
+ | `oninput` | Insert data into a control |
48
+
49
+ Mouseup, pointer movement, hover, focus, blur, scroll, and individual keyboard events do not create automatic tools. These events continue to work as ordinary UI bindings. Use an explicit `ToolDescriptor` for additional authored operations.
50
+
38
51
  The generated tool name keeps the handler key and custom element tag:
39
52
 
40
53
  ```text
@@ -53,6 +66,73 @@ Popup bindings such as `^removeItem` are registered on the ancestor component th
53
66
  removeItem_in_task-list_task-item_alpha
54
67
  ```
55
68
 
69
+ ### Action metadata
70
+
71
+ Use the [WebMCP declarative API proposal's](https://github.com/webmachinelearning/webmcp/blob/main/declarative-api-explainer.md#form-attributes) `toolname` and `tooldescription` attributes on an eligible event-bound element:
72
+
73
+ ```html
74
+ <button id="details-toggle"
75
+ bind="onclick: toggleDetails"
76
+ toolname="toggle_details"
77
+ tooldescription="Expand or collapse the details panel.">
78
+ Details
79
+ </button>
80
+ ```
81
+
82
+ The proposal defines these attributes for forms; Symbiote also reads them on other controls for its automatic event tools. HTML attributes do not enable excluded event types. Explicit `ToolDescriptor` names and descriptions remain authoritative.
83
+
84
+ Description resolution uses `tooldescription`, then the control label, then an authored `toolname`, then an authored handler key. Labels use `aria-labelledby`, `aria-label`, associated labels, button/link text, or `title`; fallback label text is limited to 200 characters. Unlabeled framework-generated handlers are skipped when neither description nor tool name is supplied.
85
+
86
+ The description includes the event, control tag and label, existing element ID when non-empty, and component/list-item identity. For example:
87
+
88
+ ```text
89
+ Expand or collapse the details panel.
90
+ Event: click. Control: <button> "Details". ID: details-toggle. Component: <details-panel>.
91
+ ```
92
+
93
+ Bindings sharing a handler and source component produce one tool. An explicit description takes priority when choosing its binding; metadata and invocation target always come from that same binding. Call `component.syncWebMCPTools()` after changing labels or attributes to refresh descriptions, names, and eligibility. Name collisions use the existing `-N` suffix.
94
+
95
+ ### Data insertion
96
+
97
+ Input tools update the selected DOM control before calling its bound handler, so that handler can publish the new data through normal state bindings:
98
+
99
+ ```js
100
+ class QueryEditor extends Symbiote {
101
+ query = '';
102
+ updateQuery(event) {
103
+ this.$.query = event.target.value;
104
+ }
105
+ }
106
+ QueryEditor.template = html`
107
+ <label>Query
108
+ <input toolname="edit_query" bind="value: query; oninput: updateQuery">
109
+ </label>
110
+ `;
111
+ QueryEditor.reg('query-editor');
112
+ ```
113
+
114
+ After mounting the component, invoke `executeWebMCPTool('edit_query', { value: 'New query' })` or its native WebMCP counterpart.
115
+
116
+ | Control | Tool input |
117
+ | --- | --- |
118
+ | Text input or textarea | `{ value: string }` |
119
+ | Number or range input | `{ value: string \| number }` |
120
+ | Checkbox or radio | `{ checked: boolean }` |
121
+ | Single select | `{ value: string }` from enabled options |
122
+ | Multiple select | `{ value: string[] }` from enabled options |
123
+
124
+ `oninput` requires a value. `onchange` also accepts an empty object to invoke the handler against the current control state. Invalid input, unsupported select options, and disabled/read-only/inert controls cannot insert data. File inputs and controls without a supported value interface need explicit tools. Automatic handlers retain the synthetic event with `type: 'webmcp'` and the selected control as `target` and `currentTarget`.
125
+
126
+ ### Native forms
127
+
128
+ Annotated forms with both `toolname` and `tooldescription` use the browser's declarative WebMCP implementation when available. Symbiote checks the document's imperative API and the declarative `SubmitEvent.agentInvoked` / `respondWith()` extensions. Imperative support alone does not cause forms to be skipped.
129
+
130
+ Symbiote omits a duplicate automatic submission tool for the form, including an associated submit control bound to the same handler. Independent control actions remain eligible. The browser owns form schemas, `toolparamdescription`, submission responses, and the user-review behavior controlled by `toolautosubmit`.
131
+
132
+ Without native declarative support, an annotated form can use the bound-handler fallback when `toolautosubmit` is present. Otherwise the fallback submission tool is omitted because it cannot represent the browser's user-review flow. Ordinary UI submission continues to work. Unannotated forms retain normal automatic handler discovery.
133
+
134
+ Browser-owned forms appear in native WebMCP discovery. `getActiveWebMCPTools()` and `executeWebMCPTool()` cover Symbiote-created tools; they do not mirror browser-owned form tools.
135
+
56
136
  ## Explicit Tool Descriptors
57
137
 
58
138
  Use `ToolDescriptor` for descriptions, input schemas, execution logic, and dynamic visibility:
@@ -141,7 +141,7 @@ export class BaseClass extends Symbiote {
141
141
  * @param {boolean} [force]
142
142
  */
143
143
  set$(values, force = false) {
144
- let itemUpdate = Reflect.has(this, DICT.MCP_ITEM_INDEX_KEY) && Object.keys(values).some(isDataKey);
144
+ let itemUpdate = Reflect.has(this, DICT.ITEM_INDEX_KEY) && Object.keys(values).some(isDataKey);
145
145
  if (itemUpdate) {
146
146
  this.actionBindings.invalidate();
147
147
  }
@@ -154,7 +154,7 @@ export class BaseClass extends Symbiote {
154
154
  * @param {boolean} [rewrite]
155
155
  */
156
156
  add$(values, rewrite = false) {
157
- if (Reflect.has(this, DICT.MCP_ITEM_INDEX_KEY) && Object.keys(values).some(isDataKey)) {
157
+ if (Reflect.has(this, DICT.ITEM_INDEX_KEY) && Object.keys(values).some(isDataKey)) {
158
158
  this.actionBindings.invalidate();
159
159
  }
160
160
  super.add$(values, rewrite);
@@ -53,6 +53,21 @@ Enable automatic UI tools on the external entry script:
53
53
 
54
54
  The literal `"true"` loads WebMCP and enables automatic tools for foundation components before they initialize, including generated items and imported fragments. At startup, the entry reads `document.currentScript` when available, otherwise the first external module script marked `webmcp-mode="true"`. This also supports CDN module wrappers whose URL differs from the imported implementation. The flag is read before asynchronous loading; an available current script takes precedence, including an absent or `"false"` flag. Without an opted-in loader, existing WebMCP settings stay unchanged. The full example opts in; the compact Todo keeps the default. Programmatic imports can use the native [WebMCP activation API](../docs/webmcp.md#activation).
55
55
 
56
+ Automatic tools cover click, submit, change, and input operations. Incidental events such as mouseup and focus retain normal UI behavior without creating tools. Set `toolname` and `tooldescription` on an operation's control to provide a useful public name and description. Generated handlers without a description, label, or authored tool name are skipped. Descriptions include the event, control label, existing element ID, and component context.
57
+
58
+ For an existing `UI/note` property:
59
+
60
+ ```html
61
+ <label>Note
62
+ <input id="note-editor" toolname="edit_note" tooldescription="Edit the current note."
63
+ bind="value: UI/note; oninput: [pub-to]UI/note">
64
+ </label>
65
+ ```
66
+
67
+ Calling `executeWebMCPTool('edit_note', { value: 'New note' })` inserts the text and invokes the declared publication handler. Change tools also support checkbox/radio `checked` booleans and select values. See [data insertion](../docs/webmcp.md#data-insertion) for schemas and control support.
68
+
69
+ Forms with native declarative WebMCP support own their submission tools; Symbiote avoids registering the same submission twice. `toolparamdescription` and `toolautosubmit` retain their native meanings. Without native support, annotated forms that require user review do not receive an immediate-submit fallback. See [native forms](../docs/webmcp.md#native-forms) for discovery and fallback behavior. WebMCP's dictionary and binding implementation remain optional imports.
70
+
56
71
  ## Examples
57
72
 
58
73
  - [todo-ref.html](./examples/todo-ref.html): a compact, unstyled Todo with creation, editing, completion and removal.
@@ -70,7 +85,7 @@ Use Send tasks in JSON requests with an HTTP endpoint that accepts the configure
70
85
  - `sym-context` without `ctx` owns local state. With `ctx="APP"`, its local data and `APP/property` refer to the same native PubSub context. Named contexts need unique owners; an existing store is never overwritten.
71
86
  - `bind="$: APP/contact"` uses native shallow merging: supplied fields update, missing fields are registered, and omitted fields remain. It does not replace the local state proxy or publish changes back automatically.
72
87
  - Optional `pub-to="APP/contact"` publishes a fresh data object after an owned field changes. Incoming merges do not echo. The target must already exist in another context. Use native bindings for incoming state and explicit outgoing publication for edits.
73
- - `process-inner-html="false"` disables an owner's inner binding parsing. Nested foundation elements still own and process their contents. The default is `true`.
88
+ - `process-inner-html="false"` disables an owner's inner binding parsing. An enclosing template can still bind through this explicitly non-parsing layout, without a second parsing pass. Other nested foundation elements own and process their contents. The default is `true`.
74
89
  - Removal releases subscriptions and owned named contexts after the native destruction delay. A move retains state; reconnecting a destroyed instance restores its authored markup and latest data.
75
90
  - JSON keys are data-only local properties. Context prefixes and prototype-related keys are rejected. Only trusted templates and binding declarations belong in authored HTML.
76
91
 
@@ -120,7 +120,9 @@ export class ActionBindings {
120
120
  subscriptions: [],
121
121
  };
122
122
  this.bindings.push(binding);
123
- this.owner.localCtx.add(key, (/** @type {ActionEvent} */ event) => this.activate(binding, event));
123
+ let handler = (/** @type {ActionEvent} */ event) => this.activate(binding, event);
124
+ handler[DICT.GENERATED_HANDLER_KEY] = true;
125
+ this.owner.localCtx.add(key, handler);
124
126
  if (element instanceof HTMLFormElement && property === 'onsubmit') {
125
127
  configuredForms.add(element);
126
128
  }
@@ -212,7 +214,7 @@ export class ActionBindings {
212
214
  let node = this.owner;
213
215
  while (node) {
214
216
  let runtime = Reflect.get(node, 'actionBindings');
215
- if (Reflect.has(node, DICT.MCP_ITEM_INDEX_KEY) && runtime instanceof ActionBindings) {
217
+ if (Reflect.has(node, DICT.ITEM_INDEX_KEY) && runtime instanceof ActionBindings) {
216
218
  return {
217
219
  runtime,
218
220
  version: runtime.version,
@@ -29,7 +29,7 @@ export function findCollectionItem(owner) {
29
29
  if (!collection.isConnected) {
30
30
  break;
31
31
  }
32
- let id = Reflect.get(item, DICT.MCP_ITEM_KEY_KEY);
32
+ let id = Reflect.get(item, DICT.ITEM_KEY_KEY);
33
33
  if (typeof id !== 'string') {
34
34
  break;
35
35
  }
@@ -15,38 +15,38 @@
15
15
  </script>
16
16
  <div class="grid gap-4 md:grid-cols-3">
17
17
  <div class="panel grid content-start gap-3">
18
- <label>Immediate<input bind="value: immediate; oninput: [pub-to]immediate"></label>
18
+ <label>Immediate<input toolname="edit_immediate_value" tooldescription="Edit the immediate publication example; publish the new text immediately." bind="value: immediate; oninput: [pub-to]immediate"></label>
19
19
  <code class="text-sm text-muted">[pub-to]</code>
20
20
  <p class="break-words text-sm">Published: <strong>{{immediate}}</strong></p>
21
21
  </div>
22
22
  <div class="panel grid content-start gap-3">
23
- <label>200 ms<input bind="value: delay200; oninput: [pub-to-200]delay200"></label>
23
+ <label>200 ms<input toolname="edit_200ms_value" tooldescription="Edit the 200 ms debounce example; publish the text after 200 ms without further input." bind="value: delay200; oninput: [pub-to-200]delay200"></label>
24
24
  <code class="text-sm text-muted">[pub-to-200]</code>
25
25
  <p class="break-words text-sm">Published: <strong>{{delay200}}</strong></p>
26
26
  </div>
27
27
  <div class="panel grid content-start gap-3">
28
- <label>1000 ms<input bind="value: delay1000; oninput: [pub-to-1000]delay1000"></label>
28
+ <label>1000 ms<input toolname="edit_1000ms_value" tooldescription="Edit the 1000 ms debounce example; publish the text after 1000 ms without further input." bind="value: delay1000; oninput: [pub-to-1000]delay1000"></label>
29
29
  <code class="text-sm text-muted">[pub-to-1000]</code>
30
30
  <p class="break-words text-sm">Published: <strong>{{delay1000}}</strong></p>
31
31
  </div>
32
32
  </div>
33
33
  <div class="grid gap-5 lg:grid-cols-2">
34
- <form class="panel grid gap-4" action-data="ACTIONS/draft" bind="onsubmit: [set]ACTIONS/submitted">
34
+ <form class="panel grid gap-4" toolname="submit_demo_message" tooldescription="Submit the current draft message, flushing its pending text publication first." action-data="ACTIONS/draft" bind="onsubmit: [set]ACTIONS/submitted">
35
35
  <h2 class="font-semibold">Debounced input and native submission</h2>
36
- <label>Message<input required placeholder="Type, then submit immediately" bind="value: draft; oninput: [pub-to-200]draft"></label>
36
+ <label>Message<input required placeholder="Type, then submit immediately" toolname="edit_demo_message" tooldescription="Edit the draft message; publish after 200 ms or when the form is submitted." bind="value: draft; oninput: [pub-to-200]draft"></label>
37
37
  <div class="field-row">
38
38
  <button class="primary">Submit</button>
39
- <button type="button" value="" bind="onclick: [set]submitted">Clear result</button>
39
+ <button type="button" value="" toolname="clear_submitted_message" tooldescription="Clear the submitted message result." bind="onclick: [set]submitted">Clear result</button>
40
40
  </div>
41
41
  <p>Submitted: <strong>{{submitted}}</strong></p>
42
42
  </form>
43
43
  <div class="panel grid content-start gap-4">
44
44
  <h2 class="font-semibold">Typed values and boolean actions</h2>
45
- <label>Amount<input type="number" min="0" bind="value: amount; oninput: [pub-to]amount"></label>
46
- <label class="field-row"><input type="checkbox" bind="checked: ready; onchange: [pub-to]ready">Ready</label>
45
+ <label>Amount<input type="number" min="0" toolname="edit_demo_amount" tooldescription="Edit the nonnegative numeric amount in the typed-values example." bind="value: amount; oninput: [pub-to]amount"></label>
46
+ <label class="field-row"><input type="checkbox" toolname="set_demo_ready" tooldescription="Set the ready flag in the typed-values example." bind="checked: ready; onchange: [pub-to]ready">Ready</label>
47
47
  <div class="field-row flex-wrap">
48
- <button type="button" value="true" bind="onclick: [set]ready">Set ready</button>
49
- <button type="button" bind="onclick: [toggle]open">Toggle message</button>
48
+ <button type="button" value="true" toolname="mark_demo_ready" tooldescription="Set the ready flag to true." bind="onclick: [set]ready">Set ready</button>
49
+ <button type="button" toolname="toggle_demo_message" tooldescription="Show or hide the boolean-toggle example message." bind="onclick: [toggle]open">Toggle message</button>
50
50
  </div>
51
51
  <p class="text-sm text-muted">Amount: {{amount}} / ready: {{ready}}</p>
52
52
  <sym-conditional when="ACTIONS/open"><p class="rounded-lg bg-accent/10 p-3 text-accent">Shown by a boolean toggle.</p></sym-conditional>