symbiote-ui 0.3.0-alpha.63 → 0.3.0-alpha.64

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to `symbiote-ui` will be documented in this file.
 
 ## Unreleased
 
+## [0.3.0-alpha.64] - 2026-07-18
+
+### Added
+
+- Added `destructiveHint: true` under `annotations` on the descriptor for destructive action descriptors.
+- Added a `bundle` option to `registerProductContextTools()` so products can register the exact executable descriptors already used to construct their adapter and consumer.
+
+### Fixed
+
+- Removed the unused legacy `createNativeToolDescriptor()` export now that
+  registration uses canonical executable plain descriptors directly.
+- Fixed `registerWebMcpTool` to register and return the same canonical plain executable descriptor passed by the product bundle, preserving exact descriptor identity before and after refresh.
+- Fixed registration signal lifecycle using an internal `AbortController` that properly cleans up external listeners on all exits, supports idempotent unregistration, and handles undefined native disposers.
+- Fixed native capability check to read active `modelContext` markers (`nativeActive` and `supportsNativeToolDescriptor`) directly, removing public options bag overrides.
+- Fixed native options forwarding to pass exactly `signal` and `exposedTo` options to `registerTool`.
+- Fixed product registration options resolver to correctly identify options bags containing `signal` or `exposedTo`.
+- Fixed `createProductWebMcpBundle` to bind all allowed actions to their own executable plain descriptor closures, preserving action/descriptor pairing through filtering and refresh in-place, and forwarding out-of-band context arguments.
+- Fixed tool validation to fail fast with tool/action identity before the first native registration, rolling back previous registrations on partial failure.
+- Fixed runtime-context property publication to restore prior property state exactly and made producer refresh publication replacement atomic.
+
 ## [0.3.0-alpha.63] - 2026-07-17
 
 - Keep cascade-theme control foregrounds above WCAG AA after browser RGB quantization.

package/docs/platform-baseline.md

@@ -19,7 +19,7 @@ and whenever `CHROMIUM_BASELINE_TARGET` changes.
 | Declarative Shadow DOM | baseline | - | SSR process HTML, stream rendering, root shadow hydration | `HTMLTemplateElement.prototype.shadowRootMode` |
 | adoptedStyleSheets / rootStyles delivery | baseline | - | SSR rootStyles, cascade themes, constructable stylesheet delivery | `Document.prototype.adoptedStyleSheets`, `ShadowRoot.prototype.adoptedStyleSheets`, `CSSStyleSheet.prototype.replaceSync` |
 | view-transition-name custom idents | baseline | - | Workspace address serialization, panel transition targets, route animations | `CSS.supports("view-transition-name", "workspace-panel-main")` |
-| navigator.modelContext | shimmed | symbiote-webmcp-shim | WebMCP tool registration, tour context, agent-visible component actions | `navigator.modelContext` or `document.modelContext`; otherwise install `symbiote-webmcp-shim` |
+| document.modelContext | shimmed | symbiote-webmcp-shim | WebMCP tool registration, tour context, agent-visible component actions | `document.modelContext`; otherwise install `symbiote-webmcp-shim` |
 
 ## Source Notes
 
@@ -28,5 +28,5 @@ and whenever `CHROMIUM_BASELINE_TARGET` changes.
 - Declarative Shadow DOM and constructable stylesheets are required for SSR and
   rootStyles delivery paths, but hosts still own fallback rendering where a target
   browser does not expose the feature.
-- `navigator.modelContext` is intentionally shimmed until the WebMCP surface is
+- `document.modelContext` is intentionally shimmed until the WebMCP surface is
   stable in Chromium; this row is the R-UI28 exception that must be re-graded first.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "symbiote-ui",
-  "version": "0.3.0-alpha.63",
+  "version": "0.3.0-alpha.64",
   "type": "module",
   "description": "Agent-ready Web Components, layouts, themes, manifests, and UI contracts for Symbiote systems.",
   "main": "index.js",

package/skills/symbiote-ui/SKILL.md

@@ -232,7 +232,10 @@ import { registerWebMcpTool, triggerWebMcpCommand } from 'symbiote-ui/webmcp';
 let { descriptor, unregister } = await registerWebMcpTool({
   name: 'update-panel',
   description: 'Update panel state',
-  inputSchema: { type: 'object', properties: { label: { type: 'string' } } }
+  inputSchema: { type: 'object', properties: { label: { type: 'string' } } },
+  execute(input) {
+    return { label: input.label };
+  }
 });
 
 // Trigger a command (bubbles to controller via webmcp-command event)

package/skills/symbiote-ui/references/webmcp-bridge.md

@@ -8,7 +8,7 @@ Protocol (WebMCP) for model-driven tool registration and command events.
 WebMCP allows Web Components to declare themselves as "tools" that AI models
 can discover and invoke. Symbiote UI provides a bridge layer that:
 
-1. Registers component capabilities with `navigator.modelContext` (if available).
+1. Registers component capabilities with `document.modelContext` (if available).
 2. Falls back gracefully when WebMCP is not supported.
 3. Emits `webmcp-command` custom events that the runtime controller forwards via WebSocket.
 
@@ -22,7 +22,7 @@ Returns the model context provider, or `null`.
 import { getModelContext } from 'symbiote-ui/webmcp';
 
 let ctx = getModelContext(document);
-// ctx = document.modelContext || navigator.modelContext || null
+// ctx = document.modelContext || null
 ```
 
 ## createToolDescriptor(options)
@@ -73,13 +73,14 @@ let descriptor = createComponentToolDescriptor(myPanelElement, {
 | `componentClass` | `component.className` |
 | `semanticRole` | `component.agent?.semanticRole` |
 
-## registerWebMcpTool(options, target)
+## registerWebMcpTool(options, target, registrationOptions)
 
 Registers a tool with the model context provider. Falls back gracefully.
 
 ```javascript
 import { registerWebMcpTool } from 'symbiote-ui/webmcp';
 
+let abortController = new AbortController();
 let { nativeActive, descriptor, unregister } = await registerWebMcpTool({
   name: 'send-chat-message',
   description: 'Send a message in the chat panel',
@@ -87,7 +88,13 @@ let { nativeActive, descriptor, unregister } = await registerWebMcpTool({
     type: 'object',
     properties: { message: { type: 'string' } },
     required: ['message']
+  },
+  execute(input) {
+    return { sent: input.message };
   }
+}, document, {
+  signal: abortController.signal,
+  exposedTo: ['https://agent.example']
 });
 
 if (nativeActive) {
@@ -103,22 +110,37 @@ unregister();
 **Parameters:**
 | Param | Type | Default | Description |
 |-------|------|---------|-------------|
-| `options` | `object` | — | Tool descriptor options (name, description, inputSchema) |
+| `options` | `object` | — | Tool descriptor options (name, description, inputSchema, execute) |
 | `target` | `Document` | `globalThis.document` | Document for model context resolution |
+| `registrationOptions` | `object` | `{}` | Registration configuration options (e.g. signal, exposedTo) |
 
 **Returns:**
 ```javascript
 {
   nativeActive: boolean,  // true if registered with native WebMCP API
-  descriptor: object,     // The tool descriptor object
-  unregister: function    // Cleanup function
+  descriptor: object,     // The tool descriptor object (always the same canonical plain descriptor passed to registration)
+  unregister: function    // Idempotent cleanup function
 }
 ```
 
-**Fallback behavior:**
-- If `modelContext` is not available → returns `nativeActive: false` with a plain descriptor.
-- If native `ToolDescriptor` import fails → falls back to plain object.
-- `unregister()` is always safe to call (noop if no native registration).
+**Validation and Fallback behavior:**
+- **Fail-Fast Verification**: Both `registerWebMcpTool()` and `registerProductContextTools()` throw an error if `descriptor.execute` is not a function.
+- **Registration Options**: an external `signal` is mapped to the internal registration lifecycle signal passed to `document.modelContext.registerTool`; `exposedTo` is forwarded unchanged.
+- If `modelContext` is not available → returns `nativeActive: false` with the same canonical plain descriptor.
+- `unregister()` is always safe to call (noop if no native registration) and is fully idempotent.
+
+`annotations.destructiveHint` is product/MCP policy metadata for consumers such
+as a confirmation gateway. It does not imply that the browser will mediate or
+confirm a destructive execution.
+
+### Execution Context & Out-of-Band Calls
+Standard WebMCP `execute` callbacks in the browser receive exactly one argument: the tool input. In-bound executions from the host platform invoke this callback using only the `input` argument. Internal framework callers can execute the closure with a second out-of-band execution parameter containing advanced metadata like `signal`, `source`, `descriptor`, and `onSettled`.
+
+When a product constructs its adapter and consumer from a prebuilt
+`createProductWebMcpBundle()` result, pass that result as the `bundle` option to
+`registerProductContextTools()`. Registration then uses the exact canonical
+descriptor objects from `bundle.descriptors`; it does not create a second
+descriptor set.
 
 ## triggerWebMcpCommand(element, command, args)
 

package/webmcp.js

@@ -59,30 +59,87 @@ function registrationUnregister(registration) {
   return () => registration?.dispose?.() || registration?.unregister?.();
 }
 
-export async function createNativeToolDescriptor(options) {
-  let { ToolDescriptor } = await import('@symbiotejs/symbiote/webmcp');
-  return new ToolDescriptor(options);
+function createRegistrationAbortError() {
+  if (typeof globalThis.DOMException === 'function') {
+    return new DOMException('Registration aborted', 'AbortError');
+  }
+  let error = new Error('Registration aborted');
+  error.name = 'AbortError';
+  return error;
 }
 
 export async function registerWebMcpTool(options, target = globalThis.document, registrationOptions = {}) {
+  let identity = options?.name || 'unknown';
+  if (!options || typeof options.execute !== 'function') {
+    throw new Error(`ToolDescriptor ${identity} requires an execute function`);
+  }
+
+  let externalSignal = registrationOptions?.signal;
+  if (externalSignal?.aborted) {
+    throw externalSignal.reason === undefined
+      ? createRegistrationAbortError()
+      : externalSignal.reason;
+  }
+
   let context = getModelContext(target);
   if (!context || typeof context.registerTool !== 'function') {
-    return { nativeActive: false, descriptor: createToolDescriptor(options), unregister: () => {} };
+    return { nativeActive: false, descriptor: options, unregister: () => {} };
   }
 
   let nativeActive = true;
-  let descriptor;
   if (typeof globalThis.HTMLElement !== 'function') {
     nativeActive = false;
-    descriptor = createToolDescriptor(options);
-  } else try {
-    descriptor = await createNativeToolDescriptor(options);
-  } catch {
+  }
+  if (context.nativeActive === false || context.supportsNativeToolDescriptor === false) {
     nativeActive = false;
-    descriptor = createToolDescriptor(options);
   }
-  let registration = await context.registerTool(descriptor, registrationOptions);
-  let unregister = registrationUnregister(registration);
+
+  let descriptor = options;
+
+  let internalController = new AbortController();
+  let internalSignal = internalController.signal;
+
+  let isUnregistered = false;
+  let unregister = (reason) => {
+    if (isUnregistered) return;
+    isUnregistered = true;
+
+    if (externalSignal) {
+      externalSignal.removeEventListener('abort', onExternalAbort);
+    }
+    if (!internalSignal.aborted) {
+      if (reason !== undefined) {
+        internalController.abort(reason);
+      } else {
+        internalController.abort();
+      }
+    }
+  };
+
+  let onExternalAbort = () => {
+    unregister(externalSignal?.reason);
+  };
+
+  if (externalSignal) {
+    externalSignal.addEventListener('abort', onExternalAbort, { once: true });
+  }
+
+  let nativeOptions = { signal: internalSignal };
+  if (registrationOptions && registrationOptions.exposedTo !== undefined) {
+    nativeOptions.exposedTo = registrationOptions.exposedTo;
+  }
+
+  try {
+    await context.registerTool(descriptor, nativeOptions);
+  } catch (err) {
+    if (externalSignal) {
+      externalSignal.removeEventListener('abort', onExternalAbort);
+    }
+    if (!internalSignal.aborted) {
+      internalController.abort();
+    }
+    throw err;
+  }
 
   return { nativeActive, descriptor, unregister };
 }
@@ -172,12 +229,34 @@ function looksLikeRuntimeContext(value) {
 }
 
 function resolveProductContextToolOptions(targetOrOptions, runtimeInput) {
+  let res;
+  let isOptionsBag = false;
   if (isObject(targetOrOptions)
     && !targetOrOptions.modelContext
     && typeof targetOrOptions.registerTool !== 'function'
-    && typeof targetOrOptions.createElement !== 'function'
-    && ('target' in targetOrOptions || 'runtime' in targetOrOptions || 'publishContext' in targetOrOptions)) {
-    return {
+    && typeof targetOrOptions.createElement !== 'function') {
+    let optionsKeys = [
+      'target',
+      'bundle',
+      'runtime',
+      'publishContext',
+      'executeAction',
+      'registrationOptions',
+      'safeActions',
+      'enrichContext',
+      'enrichRuntime',
+      'enrichActionDescriptor',
+      'signal',
+      'exposedTo'
+    ];
+    if (optionsKeys.some(key => key in targetOrOptions)) {
+      isOptionsBag = true;
+    }
+  }
+
+  if (isOptionsBag) {
+    res = {
+      ...targetOrOptions,
       target: targetOrOptions.target || globalThis.document,
       runtime: targetOrOptions.runtime,
       safeActions: targetOrOptions.safeActions,
@@ -185,20 +264,27 @@ function resolveProductContextToolOptions(targetOrOptions, runtimeInput) {
       enrichRuntime: targetOrOptions.enrichRuntime,
       enrichActionDescriptor: targetOrOptions.enrichActionDescriptor,
       publishContext: targetOrOptions.publishContext !== false,
+      registrationOptions: targetOrOptions.registrationOptions,
     };
-  }
-  if (looksLikeRuntimeContext(targetOrOptions) && runtimeInput === undefined) {
-    return {
+  } else if (looksLikeRuntimeContext(targetOrOptions) && runtimeInput === undefined) {
+    res = {
       target: globalThis.document,
       runtime: targetOrOptions,
       publishContext: true,
     };
+  } else {
+    res = {
+      target: targetOrOptions || globalThis.document,
+      runtime: runtimeInput,
+      publishContext: true,
+    };
+    if (isObject(targetOrOptions)) {
+      res.executeAction = targetOrOptions.executeAction;
+      res.signal = targetOrOptions.signal;
+      res.exposedTo = targetOrOptions.exposedTo;
+    }
   }
-  return {
-    target: targetOrOptions || globalThis.document,
-    runtime: runtimeInput,
-    publishContext: true,
-  };
+  return res;
 }
 
 function createProductRuntimeContextPayload(contextView) {
@@ -227,7 +313,156 @@ function callContextPublisher(modelContext, methodName, payload) {
   };
 }
 
-export function publishProductRuntimeContext(contextView, target = globalThis.document) {
+const PRODUCT_RUNTIME_PUBLICATION_STATE = Symbol('productRuntimePublicationState');
+const PRODUCT_RUNTIME_CONTEXT_PROPERTIES = [PRODUCT_RUNTIME_CONTEXT_NAME, 'productRuntimeContext'];
+
+function snapshotOwnPropertyState(target, property) {
+  let descriptor = Object.getOwnPropertyDescriptor(target, property);
+  try {
+    return { descriptor, valueReadable: true, value: target[property] };
+  } catch {
+    return { descriptor, valueReadable: false, value: undefined };
+  }
+}
+
+function propertyDescriptorsEqual(left, right) {
+  if (!left || !right) return left === right;
+  if (left.configurable !== right.configurable || left.enumerable !== right.enumerable) return false;
+  let leftIsData = 'value' in left || 'writable' in left;
+  let rightIsData = 'value' in right || 'writable' in right;
+  if (leftIsData !== rightIsData) return false;
+  if (leftIsData) {
+    return left.writable === right.writable && Object.is(left.value, right.value);
+  }
+  return left.get === right.get && left.set === right.set;
+}
+
+function propertyStatesEqual(left, right) {
+  if (!propertyDescriptorsEqual(left.descriptor, right.descriptor)) return false;
+  if (left.valueReadable !== right.valueReadable) return false;
+  return !left.valueReadable || Object.is(left.value, right.value);
+}
+
+function restoreOwnPropertyState(target, property, state) {
+  if (state.descriptor) {
+    Object.defineProperty(target, property, state.descriptor);
+    if (!('value' in state.descriptor) && state.valueReadable) {
+      let current = snapshotOwnPropertyState(target, property);
+      let valueDiffers = !current.valueReadable || !Object.is(current.value, state.value);
+      if (typeof state.descriptor.set === 'function' && valueDiffers) {
+        try {
+          Reflect.set(target, property, state.value, target);
+        } catch {}
+        Object.defineProperty(target, property, state.descriptor);
+      } else if (typeof state.descriptor.set !== 'function' && valueDiffers) {
+        throw new Error(`Unable to restore ${property}`);
+      }
+    }
+    if (!propertyStatesEqual(snapshotOwnPropertyState(target, property), state)) {
+      throw new Error(`Unable to restore ${property}`);
+    }
+    return;
+  }
+
+  if (!Reflect.deleteProperty(target, property)) {
+    throw new Error(`Unable to restore ${property}`);
+  }
+  let current = snapshotOwnPropertyState(target, property);
+  if (state.valueReadable && (!current.valueReadable || !Object.is(current.value, state.value))) {
+    if (!Reflect.set(target, property, state.value, target)) {
+      throw new Error(`Unable to restore ${property}`);
+    }
+    if (Object.hasOwn(target, property) && !Reflect.deleteProperty(target, property)) {
+      throw new Error(`Unable to restore ${property}`);
+    }
+  }
+  if (!propertyStatesEqual(snapshotOwnPropertyState(target, property), state)) {
+    throw new Error(`Unable to restore ${property}`);
+  }
+}
+
+function restorePropertyPublication(target, published, baseline) {
+  let errors = [];
+  for (let property of [...PRODUCT_RUNTIME_CONTEXT_PROPERTIES].reverse()) {
+    try {
+      let current = snapshotOwnPropertyState(target, property);
+      if (propertyStatesEqual(current, published.get(property))) {
+        restoreOwnPropertyState(target, property, baseline.get(property));
+      }
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+  if (errors.length) {
+    throw new AggregateError(errors, 'Failed to restore product runtime context publication');
+  }
+}
+
+function createPropertyRuntimeContextPublication(modelContext, payload, replaces) {
+  let immediateBaseline = new Map(PRODUCT_RUNTIME_CONTEXT_PROPERTIES.map((property) => (
+    [property, snapshotOwnPropertyState(modelContext, property)]
+  )));
+  let replacedState = replaces?.[PRODUCT_RUNTIME_PUBLICATION_STATE];
+  let finalBaseline = new Map(PRODUCT_RUNTIME_CONTEXT_PROPERTIES.map((property) => {
+    let current = immediateBaseline.get(property);
+    let canInherit = replacedState?.type === 'property'
+      && replacedState.active
+      && replacedState.modelContext === modelContext
+      && propertyStatesEqual(current, replacedState.published.get(property));
+    return [property, canInherit ? replacedState.finalBaseline.get(property) : current];
+  }));
+  let published = new Map();
+  let attempted = [];
+
+  try {
+    for (let property of PRODUCT_RUNTIME_CONTEXT_PROPERTIES) {
+      attempted.push(property);
+      modelContext[property] = payload.value;
+      published.set(property, snapshotOwnPropertyState(modelContext, property));
+    }
+  } catch (error) {
+    let rollbackErrors = [];
+    for (let property of attempted.reverse()) {
+      try {
+        restoreOwnPropertyState(modelContext, property, immediateBaseline.get(property));
+      } catch (rollbackError) {
+        rollbackErrors.push(rollbackError);
+      }
+    }
+    if (rollbackErrors.length) {
+      throw new AggregateError([error, ...rollbackErrors], error.message, { cause: error });
+    }
+    throw error;
+  }
+
+  let state = {
+    type: 'property',
+    modelContext,
+    published,
+    finalBaseline,
+    active: true,
+    rollback() {
+      if (!state.active) return;
+      state.active = false;
+      restorePropertyPublication(modelContext, published, immediateBaseline);
+    },
+    unregister() {
+      if (!state.active) return;
+      state.active = false;
+      restorePropertyPublication(modelContext, published, finalBaseline);
+    },
+  };
+  return {
+    published: true,
+    nativeActive: false,
+    method: 'property',
+    payload,
+    unregister: state.unregister,
+    [PRODUCT_RUNTIME_PUBLICATION_STATE]: state,
+  };
+}
+
+function publishProductRuntimeContextInternal(contextView, target, replaces = null) {
   let modelContext = getModelContext(target);
   let payload = createProductRuntimeContextPayload(contextView);
   if (!modelContext) {
@@ -243,22 +478,20 @@ export function publishProductRuntimeContext(contextView, target = globalThis.do
     }
   }
 
-  modelContext[PRODUCT_RUNTIME_CONTEXT_NAME] = payload.value;
-  modelContext.productRuntimeContext = payload.value;
-  return {
-    published: true,
-    nativeActive: false,
-    method: 'property',
-    payload,
-    unregister() {
-      if (modelContext[PRODUCT_RUNTIME_CONTEXT_NAME] === payload.value) {
-        delete modelContext[PRODUCT_RUNTIME_CONTEXT_NAME];
-      }
-      if (modelContext.productRuntimeContext === payload.value) {
-        delete modelContext.productRuntimeContext;
-      }
-    },
-  };
+  return createPropertyRuntimeContextPublication(modelContext, payload, replaces);
+}
+
+function rollbackRuntimeContextPublication(publication) {
+  let state = publication?.[PRODUCT_RUNTIME_PUBLICATION_STATE];
+  if (state?.type === 'property') {
+    state.rollback();
+    return;
+  }
+  publication?.unregister?.();
+}
+
+export function publishProductRuntimeContext(contextView, target = globalThis.document) {
+  return publishProductRuntimeContextInternal(contextView, target);
 }
 
 function resolveProductAction(context, action = {}) {
@@ -282,6 +515,7 @@ export function createProductActionToolDescriptor(productContext, action) {
   let context = normalizeProductContext(productContext);
   let actionRecord = resolveProductAction(context, action);
   let productDescription = context.webmcp.productDescription;
+  let isDestructive = Boolean(actionRecord.destructive);
   return createToolDescriptor({
     name: actionRecord.name,
     description: [
@@ -302,7 +536,8 @@ export function createProductActionToolDescriptor(productContext, action) {
       entityRefs: actionRecord.entityRefs || [],
       viewRefs: actionRecord.viewRefs || [],
       permission: actionRecord.permission || '',
-      destructive: Boolean(actionRecord.destructive),
+      destructive: isDestructive,
+      destructiveHint: isDestructive,
       allowed: actionRecord.allowed !== false,
       actionPolicy: context.webmcp.actionPolicy,
       intent: actionRecord.intent || {},
@@ -1535,11 +1770,34 @@ export function createProductWebMcpBundle(productContext, options = {}) {
   }
 
   let agentView = createProductContextAgentView(context);
-  let descriptors = createProductContextToolDescriptors(context);
+  let allowedActions = context.actions.filter((action) => action.allowed !== false);
+  let descriptors = allowedActions.map((action) => createProductActionToolDescriptor(context, action));
+
   if (typeof options.enrichActionDescriptor === 'function') {
-    descriptors = descriptors.map((descriptor, index) => (
-      options.enrichActionDescriptor({ ...descriptor }, context.actions[index], context) || descriptor
-    ));
+    descriptors = descriptors.map((descriptor, index) => {
+      let action = allowedActions[index];
+      return options.enrichActionDescriptor({ ...descriptor }, action, context) || descriptor;
+    });
+  }
+
+  if (typeof options.executeAction === 'function') {
+    descriptors.forEach((descriptor, index) => {
+      let action = allowedActions[index];
+      descriptor.execute = function(input, outOfBand) {
+        let oob = (outOfBand && typeof outOfBand === 'object') ? outOfBand : {};
+        let currentDescriptor = oob.descriptor || descriptor;
+        let command = { tool: currentDescriptor.name || descriptor.name, input };
+        let executionContext = {
+          action,
+          descriptor: currentDescriptor,
+          productContext: context,
+          signal: oob.signal,
+          source: oob.source,
+          onSettled: oob.onSettled,
+        };
+        return options.executeAction(command, executionContext);
+      };
+    });
   }
 
   return {
@@ -1553,6 +1811,25 @@ export function createProductWebMcpBundle(productContext, options = {}) {
   };
 }
 
+function validateProductWebMcpBundle(bundle) {
+  if (!isObject(bundle)) {
+    throw new Error('Product WebMCP bundle must be an object');
+  }
+  if (!isObject(bundle.context)) {
+    throw new Error('Product WebMCP bundle requires context');
+  }
+  if (!isObject(bundle.contextView)) {
+    throw new Error('Product WebMCP bundle requires contextView');
+  }
+  if (!isObject(bundle.agentView)) {
+    throw new Error('Product WebMCP bundle requires agentView');
+  }
+  if (!Array.isArray(bundle.descriptors)) {
+    throw new Error('Product WebMCP bundle requires a descriptors array');
+  }
+  return bundle;
+}
+
 function entryCandidateValue(entry, key) {
   if (!entry || !key) return undefined;
   if (entry[key] !== undefined) return entry[key];
@@ -1762,20 +2039,57 @@ export function createWebMcpHooks({ observer } = {}) {
 
 export async function registerProductContextTools(productContext, targetOrOptions = globalThis.document, runtimeInput) {
   let options = resolveProductContextToolOptions(targetOrOptions, runtimeInput);
+  let bundle = options.bundle === undefined
+    ? createProductWebMcpBundle(productContext, options)
+    : validateProductWebMcpBundle(options.bundle);
   let {
     context,
     agentView,
     contextView,
-    runtime,
     descriptors,
-  } = createProductWebMcpBundle(productContext, options);
+  } = bundle;
+
+  for (let [index, descriptor] of descriptors.entries()) {
+    if (!isObject(descriptor)) {
+      throw new Error(`Product WebMCP bundle descriptor ${index} must be an object`);
+    }
+    if (typeof descriptor.execute !== 'function') {
+      let identity = descriptor.name || descriptor.annotations?.actionId || 'unknown';
+      throw new Error(`ToolDescriptor ${identity} requires an execute function`);
+    }
+  }
+
   let registrations = [];
-  for (let descriptor of descriptors) {
-    registrations.push(await registerWebMcpTool(descriptor, options.target));
+  let publication = { published: false, nativeActive: false, method: '', payload: null, unregister: () => {} };
+  try {
+    for (let descriptor of descriptors) {
+      let regOpts = {};
+      if (typeof options.registrationOptions === 'function') {
+        regOpts = options.registrationOptions(descriptor) || {};
+      } else if (isObject(options.registrationOptions)) {
+        regOpts = options.registrationOptions;
+      } else {
+        regOpts = {
+          signal: options.signal,
+          exposedTo: options.exposedTo,
+        };
+      }
+      registrations.push(await registerWebMcpTool(descriptor, options.target, regOpts));
+    }
+    if (options.publishContext) {
+      publication = publishProductRuntimeContext(contextView, options.target);
+    }
+  } catch (err) {
+    try {
+      publication.unregister?.();
+    } catch {}
+    for (let reg of [...registrations].reverse()) {
+      try {
+        reg.unregister?.();
+      } catch {}
+    }
+    throw err;
   }
-  let publication = options.publishContext
-    ? publishProductRuntimeContext(contextView, options.target)
-    : { published: false, nativeActive: false, method: '', payload: null, unregister: () => {} };
   let producer = {
     nativeActive: registrations.some((registration) => registration.nativeActive),
     context,
@@ -1786,19 +2100,88 @@ export async function registerProductContextTools(productContext, targetOrOption
     descriptors,
     registrations,
     refresh(nextRuntime = options.runtime, refreshOptions = {}) {
-      let refreshed = createProductWebMcpBundle(context, {
+      let refreshedOptions = {
         ...options,
         ...refreshOptions,
         runtime: nextRuntime,
         publishContext: false,
-      });
-      contextView = refreshed.contextView;
-      producer.contextView = contextView;
-      producer.runtime = contextView.runtime;
-      if (options.publishContext !== false && refreshOptions.publishContext !== false) {
-        publication.unregister?.();
-        publication = publishProductRuntimeContext(contextView, refreshOptions.target || options.target);
-        producer.publication = publication;
+      };
+      delete refreshedOptions.bundle;
+      let refreshed = createProductWebMcpBundle(context, refreshedOptions);
+      let descriptorUpdates = producer.descriptors.map((descriptor) => ({
+        descriptor,
+        snapshot: Object.getOwnPropertyDescriptors(descriptor),
+        refreshed: refreshed.descriptors.find(
+          (candidate) => candidate.name === descriptor.name
+            || (candidate.annotations?.actionId && candidate.annotations.actionId === descriptor.annotations?.actionId)
+        ),
+      }));
+      let shouldPublish = options.publishContext !== false && refreshOptions.publishContext !== false;
+      let previousPublication = publication;
+      let stagedPublication = shouldPublish
+        ? publishProductRuntimeContextInternal(
+          refreshed.contextView,
+          refreshOptions.target || options.target,
+          previousPublication,
+        )
+        : previousPublication;
+      let producerSnapshot = Object.getOwnPropertyDescriptors(producer);
+
+      try {
+        for (let update of descriptorUpdates) {
+          if (!update.refreshed) continue;
+          let previousExecute = update.descriptor.execute;
+          for (let key of Object.keys(update.descriptor)) {
+            if (key === 'execute' && typeof update.refreshed.execute !== 'function') continue;
+            if (!(key in update.refreshed)) delete update.descriptor[key];
+          }
+          Object.assign(update.descriptor, update.refreshed);
+          if (typeof update.refreshed.execute !== 'function') {
+            update.descriptor.execute = previousExecute;
+          }
+        }
+
+        producer.contextView = refreshed.contextView;
+        producer.runtime = refreshed.contextView.runtime;
+        if (shouldPublish) producer.publication = stagedPublication;
+        contextView = refreshed.contextView;
+        if (shouldPublish) publication = stagedPublication;
+      } catch (error) {
+        let rollbackErrors = [];
+        for (let update of [...descriptorUpdates].reverse()) {
+          try {
+            for (let key of Reflect.ownKeys(update.descriptor)) {
+              if (!Object.hasOwn(update.snapshot, key) && !Reflect.deleteProperty(update.descriptor, key)) {
+                throw new Error(`Unable to restore descriptor ${update.descriptor.name || 'unknown'}`);
+              }
+            }
+            Object.defineProperties(update.descriptor, update.snapshot);
+          } catch (rollbackError) {
+            rollbackErrors.push(rollbackError);
+          }
+        }
+        try {
+          Object.defineProperties(producer, producerSnapshot);
+        } catch (rollbackError) {
+          rollbackErrors.push(rollbackError);
+        }
+        if (shouldPublish) {
+          try {
+            rollbackRuntimeContextPublication(stagedPublication);
+          } catch (rollbackError) {
+            rollbackErrors.push(rollbackError);
+          }
+        }
+        if (rollbackErrors.length) {
+          throw new AggregateError([error, ...rollbackErrors], error.message, { cause: error });
+        }
+        throw error;
+      }
+
+      if (shouldPublish) {
+        try {
+          previousPublication.unregister?.();
+        } catch {}
       }
       return producer;
     },