@mcp-native/react-native 0.6.0 → 0.8.0

package/dist/index.js

@@ -1,8 +1,68 @@
-import { createA2uiV1ActionEnvelope, validateA2uiV1SurfaceState } from "@mcp-native/a2ui";
-import { parseJsonObject, parseMcpNativeAction } from "@mcp-native/core";
+import { createA2uiV1ActionEnvelope, getA2uiV1HostExtensionManifestFingerprint, isA2uiV1HostExtensionRegistry, validateA2uiV1HostExtensionEvent, validateA2uiV1SurfaceState, } from "@mcp-native/a2ui";
+import { parseJsonObject, parseJsonValue, parseMcpNativeAction } from "@mcp-native/core";
 import { createElement, useCallback, useEffect, useMemo, useRef, useState, } from "react";
-import { createA2uiV1NativeRenderPlan, createA2uiV1NativeRenderPlanForLocalEdits, parseA2uiV1NativeOpenUrlDescriptor, resolveA2uiV1NativeEvent, resolveA2uiV1NativeOpenUrl, } from "./v1.js";
-export { createNativeButtonAdapter, createNativeTextAdapter, createNativeTextInputAdapter, createNativeViewAdapter, } from "./component-adapters.js";
+import { A2UI_V1_NATIVE_ICON_NAMES, isNativeHostExtensionRegistration, renderNativeHostExtensionRegistration, } from "./component-adapters.js";
+import { A2UI_V1_NATIVE_COMPONENT_NAMES, createA2uiV1NativeRenderPlan, createA2uiV1NativeRenderPlanForLocalEdits, parseA2uiV1NativeOpenUrlDescriptor, resolveA2uiV1NativeEvent, resolveA2uiV1NativeOpenUrl, validateA2uiV1NativeDateTimeInputChange, } from "./v1.js";
+export { A2UI_V1_NATIVE_ICON_NAMES, createNativeButtonAdapter, createNativeAudioPlayerAdapter, createNativeCheckBoxAdapter, createNativeChoicePickerAdapter, createNativeDateTimeInputAdapter, createNativeDividerAdapter, createNativeIconAdapter, createNativeImageAdapter, createNativeHostExtensionRegistration, createNativeModalAdapter, createNativeSliderAdapter, createNativeTabsAdapter, createNativeTextAdapter, createNativeTextInputAdapter, createNativeViewAdapter, createNativeVideoAdapter, } from "./component-adapters.js";
+const A2UI_V1_NATIVE_BASE_COMPONENT_NAMES = Object.freeze([
+    "Button",
+    "Card",
+    "Column",
+    "List",
+    "Row",
+    "Text",
+    "TextField",
+]);
+const A2UI_V1_NATIVE_OPTIONAL_COMPONENT_SLOTS = Object.freeze([
+    "AudioPlayer",
+    "CheckBox",
+    "ChoicePicker",
+    "DateTimeInput",
+    "Divider",
+    "Icon",
+    "Image",
+    "Modal",
+    "Slider",
+    "Tabs",
+    "Video",
+]);
+/** Returns the exact A2UI subset backed by one locally installed and policy-ready host catalog. */
+export function getA2uiV1NativeSupportedComponentNames(components, capabilities = {}) {
+    const installed = new Set(A2UI_V1_NATIVE_BASE_COMPONENT_NAMES);
+    for (const name of A2UI_V1_NATIVE_OPTIONAL_COMPONENT_SLOTS) {
+        if (components[name] !== undefined &&
+            (name !== "Image" || capabilities.imagePolicy !== undefined) &&
+            ((name !== "Video" && name !== "AudioPlayer") || capabilities.mediaPolicy !== undefined)) {
+            installed.add(name);
+        }
+    }
+    return Object.freeze(A2UI_V1_NATIVE_COMPONENT_NAMES.filter((name) => installed.has(name)));
+}
+/**
+ * Returns only extension catalogs backed by an exact helper-created local registration and a host
+ * capability policy. These IDs can be combined with the basic catalog in renderer capabilities.
+ */
+export function getA2uiV1NativeSupportedHostExtensionCatalogIds(components, registry, hostExtensionPolicy) {
+    if (!isA2uiV1HostExtensionRegistry(registry)) {
+        throw new TypeError("Expected an opaque negotiated host-extension registry");
+    }
+    if (hostExtensionPolicy === undefined || typeof hostExtensionPolicy !== "function") {
+        return Object.freeze([]);
+    }
+    const catalogIds = new Set();
+    for (const manifest of registry.manifests) {
+        const registrations = components.hostExtensions?.filter((registration) => isNativeHostExtensionRegistration(registration) &&
+            registration.manifest.extensionId === manifest.extensionId &&
+            registration.manifest.catalogId === manifest.catalogId &&
+            registration.manifest.schemaVersion === manifest.schemaVersion &&
+            registration.manifest.componentName === manifest.componentName) ?? [];
+        if (registrations.length === 1 &&
+            registrations[0].manifestFingerprint === getA2uiV1HostExtensionManifestFingerprint(manifest)) {
+            catalogIds.add(manifest.catalogId);
+        }
+    }
+    return Object.freeze([...catalogIds]);
+}
 /** @deprecated Use `createA2uiV1NativeRenderPlan`. */
 export function createNativeRenderPlan(surface) {
     return renderNode(surface.root);
@@ -36,7 +96,7 @@ export function McpNativeSurface({ surface, components, onAction, onBindingChang
  * Mounts the supported A2UI v1 subset with renderer-local two-way bindings.
  * Agent events are resolved against the latest local model at press time.
  */
-export function A2uiV1NativeSurface({ surface, policy, components, onAction, openUrlPolicy, onOpenUrl, onDataModelChange, actionMetadata, locale, now = currentTimestamp, }) {
+export function A2uiV1NativeSurface({ surface, policy, components, onAction, openUrlPolicy, onOpenUrl, imagePolicy, mediaPolicy, hostExtensionPolicy, onHostExtensionEvent, onDataModelChange, actionMetadata, locale, now = currentTimestamp, }) {
     const validatedSurface = useMemo(() => validateA2uiV1SurfaceState(surface, policy), [policy, surface]);
     const sourceDataModel = validatedSurface.dataModel;
     const sourceDataModelKey = createDataModelSourceKey(validatedSurface);
@@ -71,7 +131,19 @@ export function A2uiV1NativeSurface({ surface, policy, components, onAction, ope
         : createA2uiV1NativeRenderPlan)(validatedSurface, policy, {
         dataModel,
         ...(locale === undefined ? {} : { locale }),
-    }), [dataModel, locale, policy, tolerateInvalidLocalOpenUrls, validatedSurface]);
+        ...(imagePolicy === undefined ? {} : { imagePolicy }),
+        ...(mediaPolicy === undefined ? {} : { mediaPolicy }),
+        ...(hostExtensionPolicy === undefined ? {} : { hostExtensionPolicy }),
+    }), [
+        dataModel,
+        hostExtensionPolicy,
+        imagePolicy,
+        locale,
+        mediaPolicy,
+        policy,
+        tolerateInvalidLocalOpenUrls,
+        validatedSurface,
+    ]);
     const handleBindingChange = useCallback((binding, value) => {
         const next = updateDataModelBinding(dataModelRef.current, binding, value);
         dataModelRef.current = next;
@@ -116,11 +188,12 @@ export function A2uiV1NativeSurface({ surface, policy, components, onAction, ope
     }, [locale, onOpenUrl, openUrlPolicy, policy, validatedSurface]);
     return renderElement(plan, components, {
         useComponentVariants: true,
-        onBindingChange: handleBindingChange,
+        onV1BindingChange: handleBindingChange,
         onV1Event: handleEvent,
         ...(openUrlPolicy === undefined || onOpenUrl === undefined
             ? {}
             : { onV1OpenUrl: handleOpenUrl }),
+        ...(onHostExtensionEvent === undefined ? {} : { onV1HostExtensionEvent: onHostExtensionEvent }),
     });
 }
 function createDataModelSourceKey(surface) {
@@ -244,14 +317,589 @@ function renderElement(element, components, handlers) {
                 ...(invalid === undefined ? {} : { invalid }),
                 ...(validationMessages === undefined ? {} : { validationMessages }),
                 ...(value === undefined ? {} : { value }),
-                ...(binding === undefined || handlers.onBindingChange === undefined
+                ...(binding === undefined ||
+                    (handlers.onBindingChange === undefined && handlers.onV1BindingChange === undefined)
                     ? {}
                     : {
-                        onChangeText: (nextValue) => handlers.onBindingChange?.(binding, nextValue),
+                        onChangeText: (nextValue) => {
+                            if (handlers.onV1BindingChange !== undefined) {
+                                handlers.onV1BindingChange(binding, nextValue);
+                            }
+                            else {
+                                handlers.onBindingChange?.(binding, nextValue);
+                            }
+                        },
                     }),
             });
         }
+        case "Image": {
+            const uri = expectStringProp(element, "uri");
+            const fit = selectClosedStringProp(element, "fit", [
+                "contain",
+                "cover",
+                "fill",
+                "none",
+                "scaleDown",
+            ]);
+            const variant = selectClosedStringProp(element, "variant", [
+                "avatar",
+                "header",
+                "icon",
+                "largeFeature",
+                "mediumFeature",
+                "smallFeature",
+            ]);
+            const accessible = accessibilityProps.accessibilityLabel !== undefined &&
+                accessibilityProps.accessibilityElementsHidden !== true;
+            return createElement(selectImageComponent(element, components, handlers.useComponentVariants === true, variant), {
+                key: element.key,
+                uri,
+                fit,
+                resourcePolicy: expectImageResourcePolicy(element),
+                ...accessibilityProps,
+                accessible,
+                accessibilityRole: "image",
+            });
+        }
+        case "Video": {
+            const uri = expectStringProp(element, "uri");
+            const posterUri = optionalStringProp(element, "posterUri");
+            const accessible = accessibilityProps.accessibilityElementsHidden !== true;
+            return createElement(requireHostComponent(components.Video, "Video", element.key), {
+                key: element.key,
+                uri,
+                ...(posterUri === undefined ? {} : { posterUri }),
+                resourcePolicy: expectMediaResourcePolicy(element),
+                ...(posterUri === undefined
+                    ? {}
+                    : { posterResourcePolicy: expectImageResourcePolicy(element, "posterResourcePolicy") }),
+                ...accessibilityProps,
+                accessible,
+                accessibilityLabel: accessibilityProps.accessibilityLabel ?? "Video",
+                accessibilityRole: "image",
+            });
+        }
+        case "AudioPlayer": {
+            const uri = expectStringProp(element, "uri");
+            const description = optionalStringProp(element, "description");
+            const accessible = accessibilityProps.accessibilityElementsHidden !== true;
+            return createElement(requireHostComponent(components.AudioPlayer, "AudioPlayer", element.key), {
+                key: element.key,
+                uri,
+                resourcePolicy: expectMediaResourcePolicy(element),
+                ...(description === undefined ? {} : { description }),
+                ...accessibilityProps,
+                accessible,
+                accessibilityLabel: accessibilityProps.accessibilityLabel ?? description ?? "Audio",
+                accessibilityRole: "button",
+            });
+        }
+        case "HostExtension": {
+            const extensionId = expectStringProp(element, "extensionId");
+            const catalogId = expectStringProp(element, "catalogId");
+            const schemaVersion = expectStringProp(element, "schemaVersion");
+            const componentName = expectStringProp(element, "componentName");
+            const manifestFingerprint = expectStringProp(element, "manifestFingerprint");
+            const sourceComponentId = expectStringProp(element, "sourceComponentId");
+            const surfaceId = expectStringProp(element, "surfaceId");
+            const semanticProps = parseJsonObject(element.props.semanticProps, `native element ${element.key}.semanticProps`);
+            const capabilityGrant = expectHostExtensionCapabilityGrant(element);
+            const registration = requireHostExtensionRegistration(components, { extensionId, catalogId, schemaVersion, componentName, manifestFingerprint }, element.key);
+            const trustedProps = {
+                semanticProps,
+                capabilityGrant,
+                ...accessibilityProps,
+                onEvent(name, payload, options) {
+                    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+                        throw new TypeError("Expected closed host-extension event options");
+                    }
+                    const optionKeys = Object.keys(options);
+                    if (optionKeys.length !== 1 || optionKeys[0] !== "userActivated") {
+                        throw new TypeError("Expected only userActivated in host-extension event options");
+                    }
+                    const parsedPayload = validateA2uiV1HostExtensionEvent(registration.manifest, name, payload, options.userActivated);
+                    handlers.onV1HostExtensionEvent?.({
+                        extensionId,
+                        catalogId,
+                        schemaVersion,
+                        componentName,
+                        surfaceId,
+                        sourceComponentId,
+                        name,
+                        payload: parsedPayload,
+                        userActivated: options.userActivated,
+                    });
+                },
+            };
+            return renderNativeHostExtensionRegistration(registration, trustedProps, element.key);
+        }
+        case "Icon": {
+            const name = expectStringProp(element, "name");
+            if (!A2UI_V1_NATIVE_ICON_NAMES.includes(name)) {
+                throw new TypeError(`Unsupported icon name at native element ${element.key}.name`);
+            }
+            const accessible = accessibilityProps.accessibilityLabel !== undefined &&
+                accessibilityProps.accessibilityElementsHidden !== true;
+            return createElement(requireHostComponent(components.Icon, "Icon", element.key), {
+                key: element.key,
+                name: name,
+                ...accessibilityProps,
+                accessible,
+                accessibilityRole: "image",
+            });
+        }
+        case "Divider":
+            return createElement(requireHostComponent(components.Divider, "Divider", element.key), {
+                key: element.key,
+                axis: selectClosedStringProp(element, "axis", ["horizontal", "vertical"]),
+                ...accessibilityProps,
+                accessible: false,
+            });
+        case "CheckBox": {
+            const label = expectStringProp(element, "label");
+            const value = expectBooleanProp(element, "value");
+            const binding = optionalStringProp(element, "binding");
+            const invalid = optionalBooleanProp(element, "invalid");
+            const validationMessages = optionalStringArrayProp(element, "validationMessages");
+            return createElement(requireHostComponent(components.CheckBox, "CheckBox", element.key), {
+                key: element.key,
+                label,
+                value,
+                ...accessibilityProps,
+                accessible: accessibilityProps.accessibilityElementsHidden !== true,
+                accessibilityLabel: accessibilityProps.accessibilityLabel ?? label,
+                accessibilityRole: "checkbox",
+                accessibilityState: { checked: value },
+                ...(invalid === undefined ? {} : { invalid }),
+                ...(validationMessages === undefined ? {} : { validationMessages }),
+                ...(binding === undefined || handlers.onV1BindingChange === undefined
+                    ? {}
+                    : {
+                        onValueChange: (nextValue) => {
+                            if (typeof nextValue !== "boolean") {
+                                throw new TypeError(`Expected a boolean checkbox value at native element ${element.key}`);
+                            }
+                            handlers.onV1BindingChange?.(binding, nextValue);
+                        },
+                    }),
+            });
+        }
+        case "ChoicePicker": {
+            const options = expectChoicePickerOptions(element);
+            const value = expectStringArrayProp(element, "value");
+            const variant = selectClosedStringProp(element, "variant", [
+                "multipleSelection",
+                "mutuallyExclusive",
+            ]);
+            const displayStyle = selectClosedStringProp(element, "displayStyle", [
+                "checkbox",
+                "chips",
+            ]);
+            const filterable = expectBooleanProp(element, "filterable");
+            const label = optionalStringProp(element, "label");
+            const accessibilityLabel = expectStringProp(element, "accessibilityLabel");
+            const binding = optionalStringProp(element, "binding");
+            const invalid = optionalBooleanProp(element, "invalid");
+            const validationMessages = optionalStringArrayProp(element, "validationMessages");
+            return createElement(selectChoicePickerComponent(components, variant, element.key), {
+                key: element.key,
+                options,
+                value,
+                variant,
+                displayStyle,
+                filterable,
+                ...accessibilityProps,
+                accessible: accessibilityProps.accessibilityElementsHidden !== true,
+                accessibilityLabel,
+                ...(label === undefined ? {} : { label }),
+                ...(invalid === undefined ? {} : { invalid }),
+                ...(validationMessages === undefined ? {} : { validationMessages }),
+                ...(binding === undefined || handlers.onV1BindingChange === undefined
+                    ? {}
+                    : {
+                        onValueChange: (nextValue) => {
+                            const parsed = validateChoicePickerChange(nextValue, options, variant, element.key);
+                            handlers.onV1BindingChange?.(binding, parsed);
+                        },
+                    }),
+            });
+        }
+        case "Slider": {
+            const value = expectFiniteNumberProp(element, "value");
+            const minimumValue = expectFiniteNumberProp(element, "minimum");
+            const maximumValue = expectFiniteNumberProp(element, "maximum");
+            const step = optionalFiniteNumberProp(element, "step");
+            const label = optionalStringProp(element, "label");
+            const accessibilityLabel = expectStringProp(element, "accessibilityLabel");
+            const binding = optionalStringProp(element, "binding");
+            const invalid = optionalBooleanProp(element, "invalid");
+            const validationMessages = optionalStringArrayProp(element, "validationMessages");
+            return createElement(requireHostComponent(components.Slider, "Slider", element.key), {
+                key: element.key,
+                value,
+                minimumValue,
+                maximumValue,
+                ...accessibilityProps,
+                accessible: accessibilityProps.accessibilityElementsHidden !== true,
+                accessibilityLabel,
+                accessibilityRole: "adjustable",
+                ...(label === undefined ? {} : { label }),
+                ...(step === undefined ? {} : { step }),
+                ...(invalid === undefined ? {} : { invalid }),
+                ...(validationMessages === undefined ? {} : { validationMessages }),
+                ...(binding === undefined || handlers.onV1BindingChange === undefined
+                    ? {}
+                    : {
+                        onValueChange: (nextValue) => {
+                            if (typeof nextValue !== "number" ||
+                                !Number.isFinite(nextValue) ||
+                                nextValue < minimumValue ||
+                                nextValue > maximumValue ||
+                                (step !== undefined && !isSliderStepValue(nextValue, minimumValue, step))) {
+                                throw new TypeError(`Expected an in-range finite slider value at native element ${element.key}`);
+                            }
+                            handlers.onV1BindingChange?.(binding, nextValue);
+                        },
+                    }),
+            });
+        }
+        case "DateTimeInput": {
+            const value = expectStringProp(element, "value");
+            const enableDate = expectBooleanProp(element, "enableDate");
+            const enableTime = expectBooleanProp(element, "enableTime");
+            const minimum = optionalStringProp(element, "minimum");
+            const maximum = optionalStringProp(element, "maximum");
+            const label = optionalStringProp(element, "label");
+            const accessibilityLabel = expectStringProp(element, "accessibilityLabel");
+            const binding = optionalStringProp(element, "binding");
+            const invalid = optionalBooleanProp(element, "invalid");
+            const validationMessages = optionalStringArrayProp(element, "validationMessages");
+            return createElement(requireHostComponent(components.DateTimeInput, "DateTimeInput", element.key), {
+                key: element.key,
+                value,
+                enableDate,
+                enableTime,
+                ...accessibilityProps,
+                accessible: accessibilityProps.accessibilityElementsHidden !== true,
+                accessibilityLabel,
+                ...(label === undefined ? {} : { label }),
+                ...(minimum === undefined ? {} : { minimum }),
+                ...(maximum === undefined ? {} : { maximum }),
+                ...(invalid === undefined ? {} : { invalid }),
+                ...(validationMessages === undefined ? {} : { validationMessages }),
+                ...(binding === undefined || handlers.onV1BindingChange === undefined
+                    ? {}
+                    : {
+                        onValueChange: (nextValue) => {
+                            if (typeof nextValue !== "string") {
+                                throw new TypeError(`Expected a string date/time value at native element ${element.key}`);
+                            }
+                            try {
+                                validateA2uiV1NativeDateTimeInputChange(nextValue, enableDate, enableTime, minimum, maximum, `native element ${element.key}`);
+                            }
+                            catch (error) {
+                                const message = error instanceof Error
+                                    ? error.message
+                                    : `Expected a valid date/time value at native element ${element.key}`;
+                                throw new TypeError(message, { cause: error });
+                            }
+                            handlers.onV1BindingChange?.(binding, nextValue);
+                        },
+                    }),
+            });
+        }
+        case "Tabs":
+            return createElement(NativeTabsRenderer, {
+                key: element.key,
+                element,
+                components,
+                handlers,
+            });
+        case "Modal":
+            return createElement(NativeModalRenderer, {
+                key: element.key,
+                element,
+                components,
+                handlers,
+            });
+    }
+}
+function isSliderStepValue(value, minimum, step) {
+    const offset = (value - minimum) / step;
+    return (Math.abs(offset - Math.round(offset)) <= Number.EPSILON * Math.max(1, Math.abs(offset)) * 8);
+}
+function NativeTabsRenderer({ element, components, handlers, }) {
+    const tabDefinitions = expectTabDefinitions(element);
+    const children = element.children ?? [];
+    if (tabDefinitions.length !== children.length || tabDefinitions.length === 0) {
+        throw new TypeError(`Expected matching non-empty tabs and children at native element ${element.key}`);
+    }
+    const [selectedIndex, setSelectedIndex] = useState(0);
+    const currentIndex = selectedIndex < tabDefinitions.length ? selectedIndex : 0;
+    useEffect(() => {
+        if (selectedIndex >= tabDefinitions.length) {
+            setSelectedIndex(0);
+        }
+    }, [selectedIndex, tabDefinitions.length]);
+    const accessibilityProps = selectAccessibilityProps(element);
+    return createElement(requireHostComponent(components.Tabs, "Tabs", element.key), {
+        tabs: tabDefinitions.map((tab, index) => ({
+            title: tab.title,
+            content: renderChildElement(children[index], components, handlers),
+        })),
+        selectedIndex: currentIndex,
+        onSelect: (index) => {
+            if (!Number.isInteger(index) || index < 0 || index >= tabDefinitions.length) {
+                throw new TypeError(`Expected an in-range tab index at native element ${element.key}`);
+            }
+            setSelectedIndex(index);
+        },
+        ...accessibilityProps,
+        accessible: accessibilityProps.accessibilityElementsHidden !== true,
+    });
+}
+function NativeModalRenderer({ element, components, handlers, }) {
+    const children = element.children ?? [];
+    if (children.length !== 2 || children[0]?.component !== "Button") {
+        throw new TypeError(`Expected a Button trigger and content at native element ${element.key}`);
+    }
+    const [open, setOpen] = useState(false);
+    const trigger = children[0];
+    const content = children[1];
+    const outerActivation = handlers.onElementActivate;
+    const triggerElement = renderElement(trigger, components, {
+        ...handlers,
+        onElementActivate: (key) => {
+            if (key === trigger.key) {
+                setOpen(true);
+            }
+            outerActivation?.(key);
+        },
+    });
+    const contentElement = renderElement(content, components, handlers);
+    return createElement(requireHostComponent(components.Modal, "Modal", element.key), {
+        trigger: triggerElement,
+        content: contentElement,
+        open,
+        onRequestClose: () => setOpen(false),
+        ...selectAccessibilityProps(element),
+    });
+}
+function requireHostComponent(component, name, key) {
+    if (component === undefined) {
+        throw new TypeError(`Missing host component ${JSON.stringify(name)} for native element ${key}`);
+    }
+    return component;
+}
+function selectImageComponent(element, components, useComponentVariants, variant) {
+    const base = requireHostComponent(components.Image, "Image", element.key);
+    if (!useComponentVariants) {
+        return base;
+    }
+    return components.variants?.Image?.[variant] ?? base;
+}
+function selectChoicePickerComponent(components, variant, key) {
+    return (components.variants?.ChoicePicker?.[variant] ??
+        requireHostComponent(components.ChoicePicker, "ChoicePicker", key));
+}
+function expectChoicePickerOptions(element) {
+    const value = element.props.options;
+    if (!Array.isArray(value)) {
+        throw new TypeError(`Expected choice options at native element ${element.key}.options`);
+    }
+    const seen = new Set();
+    return Object.freeze(value.map((entry, index) => {
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+            throw new TypeError(`Expected a choice option at native element ${element.key}.options[${index}]`);
+        }
+        const option = entry;
+        const unknown = Object.keys(option).find((name) => name !== "label" && name !== "value");
+        if (unknown !== undefined ||
+            typeof option.label !== "string" ||
+            typeof option.value !== "string") {
+            throw new TypeError(`Expected a closed choice option at native element ${element.key}.options[${index}]`);
+        }
+        if (seen.has(option.value)) {
+            throw new TypeError(`Duplicate choice option at native element ${element.key}.options[${index}]`);
+        }
+        seen.add(option.value);
+        return Object.freeze({ label: option.label, value: option.value });
+    }));
+}
+function expectImageResourcePolicy(element, property = "resourcePolicy") {
+    const path = `native element ${element.key}.${property}`;
+    const value = parseJsonObject(element.props[property], path);
+    rejectObjectKeys(value, [
+        "allowedRedirectOrigins",
+        "cacheMode",
+        "maximumBytes",
+        "maximumDecodedHeight",
+        "maximumDecodedPixels",
+        "maximumDecodedWidth",
+        "maximumRedirects",
+    ], path);
+    const origins = value.allowedRedirectOrigins;
+    if (!Array.isArray(origins) || origins.some((origin) => typeof origin !== "string")) {
+        throw new TypeError(`Expected redirect origins at ${path}.allowedRedirectOrigins`);
+    }
+    if (value.cacheMode !== "default" && value.cacheMode !== "no-store") {
+        throw new TypeError(`Expected a closed cache mode at ${path}.cacheMode`);
+    }
+    const maximumBytes = expectObjectPositiveInteger(value, "maximumBytes", path);
+    const maximumDecodedHeight = expectObjectPositiveInteger(value, "maximumDecodedHeight", path);
+    const maximumDecodedPixels = expectObjectPositiveInteger(value, "maximumDecodedPixels", path);
+    const maximumDecodedWidth = expectObjectPositiveInteger(value, "maximumDecodedWidth", path);
+    const maximumRedirects = value.maximumRedirects;
+    if (typeof maximumRedirects !== "number" ||
+        !Number.isInteger(maximumRedirects) ||
+        maximumRedirects < 0) {
+        throw new TypeError(`Expected a non-negative integer at ${path}.maximumRedirects`);
+    }
+    return Object.freeze({
+        allowedRedirectOrigins: Object.freeze([...origins]),
+        cacheMode: value.cacheMode,
+        maximumBytes,
+        maximumDecodedHeight,
+        maximumDecodedPixels,
+        maximumDecodedWidth,
+        maximumRedirects,
+    });
+}
+function expectMediaResourcePolicy(element) {
+    const path = `native element ${element.key}.resourcePolicy`;
+    const value = parseJsonObject(element.props.resourcePolicy, path);
+    rejectObjectKeys(value, [
+        "allowedMimeTypes",
+        "allowedRedirectOrigins",
+        "allowsAutoplay",
+        "allowsBackgroundPlayback",
+        "allowsExternalRoutes",
+        "maximumBytes",
+        "maximumRedirects",
+        "requiresUserActivation",
+        "sourceOrigin",
+    ], path);
+    const sourceOrigin = expectObjectString(value, "sourceOrigin", path);
+    const allowedRedirectOrigins = expectObjectStringArray(value, "allowedRedirectOrigins", path);
+    const allowedMimeTypes = expectObjectStringArray(value, "allowedMimeTypes", path);
+    if (allowedMimeTypes.length === 0) {
+        throw new TypeError(`Expected at least one MIME type at ${path}.allowedMimeTypes`);
+    }
+    const maximumBytes = expectObjectPositiveInteger(value, "maximumBytes", path);
+    const maximumRedirects = expectObjectNonNegativeInteger(value, "maximumRedirects", path);
+    const allowsAutoplay = expectObjectBoolean(value, "allowsAutoplay", path);
+    const allowsBackgroundPlayback = expectObjectBoolean(value, "allowsBackgroundPlayback", path);
+    const allowsExternalRoutes = expectObjectBoolean(value, "allowsExternalRoutes", path);
+    const requiresUserActivation = expectObjectBoolean(value, "requiresUserActivation", path);
+    if (allowsAutoplay && requiresUserActivation) {
+        throw new TypeError(`Conflicting autoplay and activation controls at ${path}`);
+    }
+    return Object.freeze({
+        sourceOrigin,
+        allowedRedirectOrigins,
+        allowedMimeTypes,
+        maximumBytes,
+        maximumRedirects,
+        allowsAutoplay,
+        allowsBackgroundPlayback,
+        allowsExternalRoutes,
+        requiresUserActivation,
+    });
+}
+function expectHostExtensionCapabilityGrant(element) {
+    const path = `native element ${element.key}.capabilityGrant`;
+    const value = parseJsonObject(element.props.capabilityGrant, path);
+    rejectObjectKeys(value, ["permissions", "resources"], path);
+    return Object.freeze({
+        permissions: expectObjectStringArray(value, "permissions", path),
+        resources: expectObjectStringArray(value, "resources", path),
+    });
+}
+function requireHostExtensionRegistration(components, identity, key) {
+    if (!Array.isArray(components.hostExtensions)) {
+        throw new TypeError(`Missing host-extension registrations for native element ${key}`);
+    }
+    const registrations = components.hostExtensions.filter((registration) => {
+        if (!isNativeHostExtensionRegistration(registration)) {
+            throw new TypeError("Host-extension catalogs accept only helper-created registrations");
+        }
+        const manifest = registration.manifest;
+        return (manifest.extensionId === identity.extensionId &&
+            manifest.catalogId === identity.catalogId &&
+            manifest.schemaVersion === identity.schemaVersion &&
+            manifest.componentName === identity.componentName);
+    });
+    if (registrations.length !== 1) {
+        throw new TypeError(`Expected exactly one local registration for ${JSON.stringify(identity.componentName)} at native element ${key}`);
+    }
+    const registration = registrations[0];
+    if (registration.manifestFingerprint !== identity.manifestFingerprint) {
+        throw new TypeError(`Local registration manifest mismatch for ${JSON.stringify(identity.componentName)} at native element ${key}`);
     }
+    return registration;
+}
+function expectObjectStringArray(value, name, path) {
+    const field = value[name];
+    if (!Array.isArray(field) || field.some((entry) => typeof entry !== "string")) {
+        throw new TypeError(`Expected a string array at ${path}.${name}`);
+    }
+    if (new Set(field).size !== field.length) {
+        throw new TypeError(`Expected unique strings at ${path}.${name}`);
+    }
+    return Object.freeze([...field]);
+}
+function expectObjectBoolean(value, name, path) {
+    const field = value[name];
+    if (typeof field !== "boolean") {
+        throw new TypeError(`Expected a boolean at ${path}.${name}`);
+    }
+    return field;
+}
+function expectObjectNonNegativeInteger(value, name, path) {
+    const field = value[name];
+    if (typeof field !== "number" || !Number.isInteger(field) || field < 0) {
+        throw new TypeError(`Expected a non-negative integer at ${path}.${name}`);
+    }
+    return field;
+}
+function expectObjectPositiveInteger(value, name, path) {
+    const field = value[name];
+    if (typeof field !== "number" || !Number.isInteger(field) || field < 1) {
+        throw new TypeError(`Expected a positive integer at ${path}.${name}`);
+    }
+    return field;
+}
+function validateChoicePickerChange(value, options, variant, key) {
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+        throw new TypeError(`Expected an array of choice values at native element ${key}`);
+    }
+    if (new Set(value).size !== value.length) {
+        throw new TypeError(`Expected unique choice values at native element ${key}`);
+    }
+    if (variant === "mutuallyExclusive" && value.length > 1) {
+        throw new TypeError(`Expected at most one choice value at native element ${key}`);
+    }
+    const allowed = new Set(options.map((option) => option.value));
+    if (value.some((entry) => !allowed.has(entry))) {
+        throw new TypeError(`Expected known choice values at native element ${key}`);
+    }
+    return Object.freeze([...value]);
+}
+function expectTabDefinitions(element) {
+    const value = element.props.tabs;
+    if (!Array.isArray(value)) {
+        throw new TypeError(`Expected tabs at native element ${element.key}.tabs`);
+    }
+    return Object.freeze(value.map((entry, index) => {
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+            throw new TypeError(`Expected a tab at native element ${element.key}.tabs[${index}]`);
+        }
+        const tab = entry;
+        if (Object.keys(tab).some((name) => name !== "title") || typeof tab.title !== "string") {
+            throw new TypeError(`Expected a closed tab at native element ${element.key}.tabs[${index}]`);
+        }
+        return Object.freeze({ title: tab.title });
+    }));
 }
 function renderChildElement(element, components, handlers) {
     const rendered = renderElement(element, components, handlers);
@@ -394,21 +1042,36 @@ function createButtonPressHandler(element, handlers) {
         if (handlers.onAction === undefined) {
             throw new TypeError(`Missing native action handler for element ${element.key}`);
         }
-        return disabled ? () => undefined : () => handlers.onAction?.(action);
+        return disabled
+            ? () => undefined
+            : () => {
+                handlers.onElementActivate?.(element.key);
+                handlers.onAction?.(action);
+            };
     }
     if (hasEvent) {
         const event = expectV1EventProp(element);
         if (handlers.onV1Event === undefined) {
             throw new TypeError(`Missing A2UI v1 event handler for element ${element.key}`);
         }
-        return disabled ? () => undefined : () => handlers.onV1Event?.(event);
+        return disabled
+            ? () => undefined
+            : () => {
+                handlers.onElementActivate?.(element.key);
+                handlers.onV1Event?.(event);
+            };
     }
     if (hasOpenUrl) {
         const request = expectV1OpenUrlProp(element);
         if (handlers.onV1OpenUrl === undefined) {
             throw new TypeError(`Missing A2UI v1 openUrl policy or handler for element ${element.key}`);
         }
-        return disabled ? () => undefined : () => handlers.onV1OpenUrl?.(request);
+        return disabled
+            ? () => undefined
+            : () => {
+                handlers.onElementActivate?.(element.key);
+                handlers.onV1OpenUrl?.(request);
+            };
     }
     expectV1InvalidLocalOpenUrlProp(element);
     if (!disabled) {
@@ -442,6 +1105,13 @@ function expectStringProp(element, name) {
     }
     return value;
 }
+function selectClosedStringProp(element, name, allowed) {
+    const value = expectStringProp(element, name);
+    if (!allowed.includes(value)) {
+        throw new TypeError(`Unsupported value ${JSON.stringify(value)} at native element ${element.key}.${name}`);
+    }
+    return value;
+}
 function optionalStringProp(element, name) {
     const value = element.props[name];
     return value === undefined ? undefined : expectStringProp(element, name);
@@ -456,6 +1126,20 @@ function optionalStringArrayProp(element, name) {
     }
     return value;
 }
+function expectStringArrayProp(element, name) {
+    const value = optionalStringArrayProp(element, name);
+    if (value === undefined) {
+        throw new TypeError(`Expected an array of strings at native element ${element.key}.${name}`);
+    }
+    return value;
+}
+function expectBooleanProp(element, name) {
+    const value = optionalBooleanProp(element, name);
+    if (value === undefined) {
+        throw new TypeError(`Expected a boolean at native element ${element.key}.${name}`);
+    }
+    return value;
+}
 function optionalBooleanProp(element, name) {
     const value = element.props[name];
     if (value !== undefined && typeof value !== "boolean") {
@@ -470,6 +1154,13 @@ function optionalFiniteNumberProp(element, name) {
     }
     return value;
 }
+function expectFiniteNumberProp(element, name) {
+    const value = optionalFiniteNumberProp(element, name);
+    if (value === undefined) {
+        throw new TypeError(`Expected a finite number at native element ${element.key}.${name}`);
+    }
+    return value;
+}
 function optionalAccessibilityLiveProp(element) {
     const value = element.props.accessibilityLive;
     if (value === undefined || value === "assertive" || value === "off" || value === "polite") {
@@ -550,9 +1241,7 @@ function updateDataModelBinding(dataModel, binding, value) {
     if (typeof binding !== "string" || !binding.startsWith("/") || binding.length === 1) {
         throw new TypeError(`Expected a non-root absolute JSON Pointer binding, received ${JSON.stringify(binding)}`);
     }
-    if (typeof value !== "string") {
-        throw new TypeError("Expected a string renderer binding value");
-    }
+    const parsedValue = parseJsonValue(value, "renderer binding value");
     const next = parseJsonObject(dataModel, "renderer data model");
     const tokens = binding
         .slice(1)
@@ -570,10 +1259,7 @@ function updateDataModelBinding(dataModel, binding, value) {
                 throw new TypeError(`Renderer binding ${JSON.stringify(binding)} is missing`);
             }
             if (last) {
-                if (typeof cursor[arrayIndex] !== "string") {
-                    throw new TypeError(`Renderer binding ${JSON.stringify(binding)} must reference an existing string value`);
-                }
-                cursor[arrayIndex] = value;
+                cursor[arrayIndex] = validateRendererBindingReplacement(cursor[arrayIndex], parsedValue, binding);
                 break;
             }
             cursor = cursor[arrayIndex];
@@ -583,16 +1269,27 @@ function updateDataModelBinding(dataModel, binding, value) {
             throw new TypeError(`Renderer binding ${JSON.stringify(binding)} is missing`);
         }
         if (last) {
-            if (typeof cursor[token] !== "string") {
-                throw new TypeError(`Renderer binding ${JSON.stringify(binding)} must reference an existing string value`);
-            }
-            defineJsonProperty(cursor, token, value);
+            defineJsonProperty(cursor, token, validateRendererBindingReplacement(cursor[token], parsedValue, binding));
             break;
         }
         cursor = cursor[token];
     }
     return parseJsonObject(next, "renderer data model");
 }
+function validateRendererBindingReplacement(current, next, binding) {
+    if ((typeof current === "string" && typeof next === "string") ||
+        (typeof current === "boolean" && typeof next === "boolean") ||
+        (typeof current === "number" && typeof next === "number")) {
+        return next;
+    }
+    if (Array.isArray(current) &&
+        current.every((value) => typeof value === "string") &&
+        Array.isArray(next) &&
+        next.every((value) => typeof value === "string")) {
+        return Object.freeze([...next]);
+    }
+    throw new TypeError(`Renderer binding ${JSON.stringify(binding)} must preserve its string, boolean, number, or string-array value type`);
+}
 function decodePointerToken(token, pointer) {
     for (let index = 0; index < token.length; index += 1) {
         if (token[index] !== "~") {
@@ -614,5 +1311,5 @@ function defineJsonProperty(object, key, value) {
         writable: true,
     });
 }
-export { A2UI_V1_NATIVE_COMPONENT_NAMES, A2UI_V1_NATIVE_MAX_OPEN_URL_LENGTH, A2UI_V1_NATIVE_MAX_RENDER_NODES, createA2uiV1NativeRenderPlan, resolveA2uiV1NativeEvent, resolveA2uiV1NativeOpenUrl, } from "./v1.js";
+export { A2UI_V1_NATIVE_COMPONENT_NAMES, A2UI_V1_NATIVE_MAX_CHOICE_OPTIONS, A2UI_V1_NATIVE_MAX_IMAGE_BYTES, A2UI_V1_NATIVE_MAX_IMAGE_DIMENSION, A2UI_V1_NATIVE_MAX_IMAGE_PIXELS, A2UI_V1_NATIVE_MAX_IMAGE_REDIRECT_ORIGINS, A2UI_V1_NATIVE_MAX_IMAGE_REDIRECTS, A2UI_V1_NATIVE_MAX_IMAGE_URL_LENGTH, A2UI_V1_NATIVE_MAX_IMAGES, A2UI_V1_NATIVE_MAX_MEDIA, A2UI_V1_NATIVE_MAX_MEDIA_BYTES, A2UI_V1_NATIVE_MAX_MEDIA_MIME_TYPES, A2UI_V1_NATIVE_MAX_MEDIA_REDIRECT_ORIGINS, A2UI_V1_NATIVE_MAX_MEDIA_REDIRECTS, A2UI_V1_NATIVE_MAX_MEDIA_URL_LENGTH, A2UI_V1_NATIVE_MAX_OPEN_URL_LENGTH, A2UI_V1_NATIVE_MAX_RENDER_NODES, A2UI_V1_NATIVE_MAX_TOTAL_IMAGE_BYTES, A2UI_V1_NATIVE_MAX_TOTAL_IMAGE_PIXELS, A2UI_V1_NATIVE_MAX_TOTAL_MEDIA_BYTES, createA2uiV1NativeRenderPlan, resolveA2uiV1NativeEvent, resolveA2uiV1NativeOpenUrl, } from "./v1.js";
 //# sourceMappingURL=index.js.map