@mcp-native/react-native 0.2.0 → 0.3.0

package/dist/v1.js

@@ -1,5 +1,6 @@
-import { A2UI_V1_MAX_COMPONENTS, A2uiParseError, validateA2uiV1SurfaceState, } from "@mcp-native/a2ui";
-import { parseJsonObject, parseJsonValue } from "@mcp-native/core";
+import { A2UI_V1_MAX_COMPONENTS, A2UI_V1_MAX_SOURCE_LENGTH, A2uiParseError, evaluateA2uiV1FormatString, validateA2uiV1SurfaceState, } from "@mcp-native/a2ui";
+import { JSON_MAX_STRING_LENGTH, JSON_MAX_VALUES, parseJsonObject, parseJsonValue, } from "@mcp-native/core";
+import { ISO_4217_CURRENCY_CODES } from "./iso-4217.js";
 export const A2UI_V1_NATIVE_COMPONENT_NAMES = Object.freeze([
     "Button",
     "Card",
@@ -15,17 +16,121 @@ export const A2UI_V1_NATIVE_MAX_RENDER_NODES = A2UI_V1_MAX_COMPONENTS;
  * Converts a policy-validated A2UI v1 surface into the existing host-owned
  * native render plan. Unsupported renderer semantics fail closed.
  */
-export function createA2uiV1NativeRenderPlan(surface, policy) {
-    const validated = validateA2uiV1SurfaceState(surface, policy);
-    const context = {
+export function createA2uiV1NativeRenderPlan(surface, policy, options = {}) {
+    const parsedOptions = parseRenderPlanOptions(options);
+    const context = createAdapterContext(surface, policy, parsedOptions.dataModel, parsedOptions.locale);
+    return adaptComponent("root", "root", context, undefined);
+}
+/** Resolves one validated event against the latest renderer-local data model. */
+export function resolveA2uiV1NativeEvent(surface, policy, sourceComponentId, dataModel, options = {}) {
+    if (typeof sourceComponentId !== "string" || sourceComponentId.length === 0) {
+        throw new A2uiParseError("Expected a non-empty A2UI source component id");
+    }
+    const parsedOptions = parseEventResolutionOptions(options);
+    const context = createAdapterContext(surface, policy, dataModel, parsedOptions.locale);
+    const events = findNativeEvents(adaptComponent("root", "root", context, undefined), sourceComponentId, parsedOptions.instanceKey);
+    if (events.length === 0) {
+        throw new A2uiParseError(`A2UI native event source ${JSON.stringify(sourceComponentId)} is not a reachable supported Button`);
+    }
+    if (events.length > 1) {
+        throw new A2uiParseError(`A2UI native event source ${JSON.stringify(sourceComponentId)} is ambiguous without its template instance key`);
+    }
+    return events[0];
+}
+function findNativeEvents(element, sourceComponentId, instanceKey) {
+    const events = [];
+    const event = element.props.event;
+    if (event?.sourceComponentId === sourceComponentId &&
+        (instanceKey === undefined || event.instanceKey === instanceKey)) {
+        events.push(event);
+    }
+    for (const child of element.children ?? []) {
+        events.push(...findNativeEvents(child, sourceComponentId, instanceKey));
+    }
+    return events;
+}
+function createAdapterContext(surface, policy, dataModel, locale) {
+    const localDataModel = dataModel === undefined
+        ? parseJsonObject(surface.dataModel, "surface.dataModel")
+        : parseJsonObject(dataModel, "options.dataModel");
+    const validated = validateA2uiV1SurfaceState(dataModel === undefined ? surface : { ...surface, dataModel: localDataModel }, policy);
+    return {
         surface: validated,
         dataModel: parseJsonObject(validated.dataModel, "surface.dataModel"),
+        locale,
+        numberFormats: new Map(),
+        pluralRules: new Map(),
         visiting: new Set(),
+        formatStringExpressionCount: 0,
+        formattedStringLength: 0,
         renderNodeCount: 0,
     };
-    return adaptComponent("root", "root", context);
 }
-function adaptComponent(id, key, context) {
+function parseRenderPlanOptions(options) {
+    const parsed = parseOptionsObject(options, "A2UI native render plan options", [
+        "dataModel",
+        "locale",
+    ]);
+    return {
+        ...(parsed.dataModel === undefined
+            ? {}
+            : { dataModel: parseJsonObject(parsed.dataModel, "options.dataModel") }),
+        ...(parsed.locale === undefined
+            ? {}
+            : { locale: parseLocale(parsed.locale, "options.locale") }),
+    };
+}
+function parseEventResolutionOptions(options) {
+    const parsed = parseOptionsObject(options, "A2UI native event resolution options", [
+        "instanceKey",
+        "locale",
+    ]);
+    if (parsed.instanceKey !== undefined &&
+        (typeof parsed.instanceKey !== "string" || parsed.instanceKey.length === 0)) {
+        throw new A2uiParseError("Expected a non-empty A2UI native event instance key");
+    }
+    return {
+        ...(parsed.instanceKey === undefined ? {} : { instanceKey: parsed.instanceKey }),
+        ...(parsed.locale === undefined
+            ? {}
+            : { locale: parseLocale(parsed.locale, "options.locale") }),
+    };
+}
+function parseOptionsObject(value, label, allowedKeys) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new A2uiParseError(`Expected ${label} to be an object`);
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new A2uiParseError(`Expected plain ${label}`);
+    }
+    const parsed = value;
+    const unknownKey = Object.keys(parsed).find((key) => !allowedKeys.includes(key));
+    if (unknownKey !== undefined) {
+        throw new A2uiParseError(`Unexpected ${label.slice(0, -1)} ${JSON.stringify(unknownKey)}`);
+    }
+    return parsed;
+}
+function parseLocale(value, path) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 128) {
+        throw new A2uiParseError(`Expected a non-empty BCP 47 locale at ${path}`);
+    }
+    try {
+        if (Intl.NumberFormat.supportedLocalesOf(value, { localeMatcher: "lookup" }).length === 0) {
+            throw new A2uiParseError(`Unsupported BCP 47 locale ${JSON.stringify(value)} at ${path}`);
+        }
+        return new Intl.NumberFormat(value).resolvedOptions().locale;
+    }
+    catch (cause) {
+        if (cause instanceof A2uiParseError) {
+            throw cause;
+        }
+        throw new A2uiParseError(`Invalid BCP 47 locale ${JSON.stringify(value)} at ${path}`, {
+            cause,
+        });
+    }
+}
+function adaptComponent(id, key, context, scope) {
     context.renderNodeCount += 1;
     if (context.renderNodeCount > A2UI_V1_NATIVE_MAX_RENDER_NODES) {
         throw new A2uiParseError(`Expanded A2UI native plan exceeds maximum of ${A2UI_V1_NATIVE_MAX_RENDER_NODES} nodes`);
@@ -41,19 +146,19 @@ function adaptComponent(id, key, context) {
     try {
         switch (component.component) {
             case "Row":
-                return adaptContainer(component, key, "row", undefined, context);
+                return adaptContainer(component, key, "row", undefined, context, scope);
             case "Column":
-                return adaptContainer(component, key, "column", undefined, context);
+                return adaptContainer(component, key, "column", undefined, context, scope);
             case "List":
-                return adaptList(component, key, context);
+                return adaptList(component, key, context, scope);
             case "Card":
-                return adaptCard(component, key, context);
+                return adaptCard(component, key, context, scope);
             case "Text":
-                return adaptText(component, key, context);
+                return adaptText(component, key, context, scope);
             case "Button":
-                return adaptButton(component, key, context);
+                return adaptButton(component, key, context, scope);
             case "TextField":
-                return adaptTextField(component, key, context);
+                return adaptTextField(component, key, context, scope);
             default:
                 throw new A2uiParseError(`A2UI component ${JSON.stringify(id)} uses ${JSON.stringify(component.component)}, which the native adapter does not support`);
         }
@@ -62,7 +167,7 @@ function adaptComponent(id, key, context) {
         context.visiting.delete(id);
     }
 }
-function adaptContainer(component, key, layout, variant, context) {
+function adaptContainer(component, key, layout, variant, context, scope) {
     if (!Array.isArray(component.children)) {
         throw new A2uiParseError(`A2UI native adapter does not yet support dynamic children at components.${component.id}.children`);
     }
@@ -70,45 +175,77 @@ function adaptContainer(component, key, layout, variant, context) {
     if (variant !== undefined) {
         props.variant = variant;
     }
+    addContainerLayoutProps(component, props);
+    addCommonProps(component, props, context, scope);
+    return {
+        key,
+        component: "View",
+        props,
+        children: component.children.map((childId, index) => adaptComponent(childId, appendInstanceKey(key, childId, index), context, scope)),
+    };
+}
+function addContainerLayoutProps(component, props) {
     if (component.justify !== undefined) {
-        props.justify = expectString(component.justify, `components.${component.id}.justify`);
+        const justify = expectString(component.justify, `components.${component.id}.justify`);
+        if (justify === "stretch") {
+            throw new A2uiParseError(`A2UI native adapter does not support main-axis stretch at components.${component.id}.justify`);
+        }
+        props.justify = justify;
     }
     if (component.align !== undefined) {
         props.align = expectString(component.align, `components.${component.id}.align`);
     }
-    addCommonProps(component, props, context);
+}
+function adaptList(component, key, context, scope) {
+    if (Array.isArray(component.children)) {
+        return adaptContainer(component, key, component.direction === "horizontal" ? "row" : "column", "list", context, scope);
+    }
+    const template = expectObject(component.children, `components.${component.id}.children`);
+    const pointer = expectAbsoluteBinding(template.path, `components.${component.id}.children.path`);
+    const componentId = expectString(template.componentId, `components.${component.id}.children.componentId`);
+    const value = parseJsonValue(resolveJsonPointer(context.dataModel, pointer, `components.${component.id}.children`), `components.${component.id}.children`);
+    if (!Array.isArray(value)) {
+        throw new A2uiParseError(`Expected an array at components.${component.id}.children path ${JSON.stringify(pointer)}`);
+    }
+    const props = {
+        layout: component.direction === "horizontal" ? "row" : "column",
+        variant: "list",
+    };
+    addContainerLayoutProps(component, props);
+    addCommonProps(component, props, context, scope);
     return {
         key,
         component: "View",
         props,
-        children: component.children.map((childId, index) => adaptComponent(childId, `${key}/${childId}:${index}`, context)),
+        children: value.map((item, index) => adaptComponent(componentId, appendInstanceKey(key, componentId, index), context, {
+            value: item,
+            pointer: appendPointerToken(pointer, String(index)),
+            index,
+        })),
     };
 }
-function adaptList(component, key, context) {
-    return adaptContainer(component, key, component.direction === "horizontal" ? "row" : "column", "list", context);
-}
-function adaptCard(component, key, context) {
+function adaptCard(component, key, context, scope) {
     const childId = expectString(component.child, `components.${component.id}.child`);
     const props = { layout: "column", variant: "card" };
-    addCommonProps(component, props, context);
+    addCommonProps(component, props, context, scope);
     return {
         key,
         component: "View",
         props,
-        children: [adaptComponent(childId, `${key}/${childId}:0`, context)],
+        children: [adaptComponent(childId, appendInstanceKey(key, childId, 0), context, scope)],
     };
 }
-function adaptText(component, key, context) {
+function adaptText(component, key, context, scope) {
     const props = {
-        children: resolveDynamicString(component.text, `components.${component.id}.text`, context),
+        children: resolveDynamicString(component.text, `components.${component.id}.text`, context, scope),
     };
     if (component.variant !== undefined) {
         props.variant = component.variant;
     }
-    addCommonProps(component, props, context);
+    addCommonProps(component, props, context, scope);
     return { key, component: "Text", props };
 }
-function adaptButton(component, key, context) {
+function adaptButton(component, key, context, scope) {
     rejectUnsupportedChecks(component);
     const childId = expectString(component.child, `components.${component.id}.child`);
     const child = context.surface.components.get(childId);
@@ -116,38 +253,38 @@ function adaptButton(component, key, context) {
         throw new A2uiParseError(`A2UI native Button ${JSON.stringify(component.id)} requires a Text child`);
     }
     const props = {
-        title: resolveDynamicString(child.text, `components.${child.id}.text`, context),
-        event: resolveButtonEvent(component, context),
+        title: resolveDynamicString(child.text, `components.${child.id}.text`, context, scope),
+        event: resolveButtonEvent(component, key, context, scope),
     };
     if (component.variant !== undefined) {
         props.variant = component.variant;
     }
-    addCommonProps(component, props, context);
+    addCommonProps(component, props, context, scope);
     if (props.accessibilityLabel === undefined) {
         props.accessibilityLabel = props.title;
     }
     return { key, component: "Button", props };
 }
-function adaptTextField(component, key, context) {
+function adaptTextField(component, key, context, scope) {
     rejectUnsupportedChecks(component);
     const componentPath = `components.${component.id}`;
-    const label = resolveDynamicString(component.label, `${componentPath}.label`, context);
+    const label = resolveDynamicString(component.label, `${componentPath}.label`, context, scope);
     const props = {
         label,
         placeholder: component.placeholder === undefined
             ? label
-            : resolveDynamicString(component.placeholder, `${componentPath}.placeholder`, context),
+            : resolveDynamicString(component.placeholder, `${componentPath}.placeholder`, context, scope),
     };
     if (component.value !== undefined) {
-        props.value = resolveDynamicString(component.value, `${componentPath}.value`, context);
+        props.value = resolveDynamicString(component.value, `${componentPath}.value`, context, scope);
         if (isBinding(component.value)) {
-            props.binding = expectAbsoluteBinding(component.value.path, `${componentPath}.value.path`);
+            props.binding = resolveBindingPointer(component.value.path, `${componentPath}.value.path`, scope);
         }
     }
     if (component.variant !== undefined) {
         props.variant = component.variant;
     }
-    addCommonProps(component, props, context);
+    addCommonProps(component, props, context, scope);
     if (props.accessibilityLabel === undefined) {
         props.accessibilityLabel = label;
     }
@@ -158,7 +295,7 @@ function rejectUnsupportedChecks(component) {
         throw new A2uiParseError(`A2UI native adapter does not yet support renderer-side checks at components.${component.id}.checks`);
     }
 }
-function resolveButtonEvent(component, context) {
+function resolveButtonEvent(component, key, context, scope) {
     const action = expectObject(component.action, `components.${component.id}.action`);
     if (!Object.hasOwn(action, "event")) {
         throw new A2uiParseError(`A2UI native Button ${JSON.stringify(component.id)} does not support local function actions`);
@@ -168,70 +305,250 @@ function resolveButtonEvent(component, context) {
     const eventContext = expectOptionalObject(event.context, `components.${component.id}.action.event.context`);
     const resolvedContext = {};
     for (const [name, value] of Object.entries(eventContext ?? {})) {
-        defineJsonProperty(resolvedContext, name, resolveDynamicValue(value, `components.${component.id}.action.event.context.${name}`, context));
+        defineJsonProperty(resolvedContext, name, resolveDynamicValue(value, `components.${component.id}.action.event.context.${name}`, context, scope));
     }
     const userMessage = event.userMessage === undefined
         ? undefined
-        : resolveDynamicString(event.userMessage, `components.${component.id}.action.event.userMessage`, context);
+        : resolveDynamicString(event.userMessage, `components.${component.id}.action.event.userMessage`, context, scope);
     return {
         name: eventName,
         surfaceId: context.surface.surfaceId,
         sourceComponentId: component.id,
+        instanceKey: key,
         ...(userMessage === undefined ? {} : { userMessage }),
         context: parseJsonObject(resolvedContext, `components.${component.id}.action.event.context`),
     };
 }
-function addCommonProps(component, props, context) {
+function addCommonProps(component, props, context, scope) {
     if (component.weight !== undefined) {
-        props.weight = expectFiniteNumber(component.weight, `components.${component.id}.weight`);
+        const weight = expectFiniteNumber(component.weight, `components.${component.id}.weight`);
+        if (weight < 0) {
+            throw new A2uiParseError(`A2UI native adapter does not support negative weight at components.${component.id}.weight`);
+        }
+        props.weight = weight;
     }
     if (component.accessibility === undefined) {
         return;
     }
     const accessibility = expectObject(component.accessibility, `components.${component.id}.accessibility`);
     if (accessibility.label !== undefined) {
-        props.accessibilityLabel = resolveDynamicString(accessibility.label, `components.${component.id}.accessibility.label`, context);
+        props.accessibilityLabel = resolveDynamicString(accessibility.label, `components.${component.id}.accessibility.label`, context, scope);
     }
     if (accessibility.description !== undefined) {
-        props.accessibilityHint = resolveDynamicString(accessibility.description, `components.${component.id}.accessibility.description`, context);
+        props.accessibilityHint = resolveDynamicString(accessibility.description, `components.${component.id}.accessibility.description`, context, scope);
     }
     if (accessibility.live !== undefined) {
         props.accessibilityLive = accessibility.live;
     }
     if (accessibility.hidden !== undefined) {
-        props.accessibilityHidden = resolveDynamicBoolean(accessibility.hidden, `components.${component.id}.accessibility.hidden`, context);
+        props.accessibilityHidden = resolveDynamicBoolean(accessibility.hidden, `components.${component.id}.accessibility.hidden`, context, scope);
     }
 }
-function resolveDynamicString(value, path, context) {
-    const resolved = resolveDynamicValue(value, path, context);
+function resolveDynamicString(value, path, context, scope) {
+    const resolved = resolveDynamicValue(value, path, context, scope);
     return expectString(resolved, path);
 }
-function resolveDynamicBoolean(value, path, context) {
-    const resolved = resolveDynamicValue(value, path, context);
+function resolveDynamicBoolean(value, path, context, scope) {
+    const resolved = resolveDynamicValue(value, path, context, scope);
     if (typeof resolved !== "boolean") {
         throw new A2uiParseError(`Expected a boolean at ${path}`);
     }
     return resolved;
 }
-function resolveDynamicValue(value, path, context) {
+function resolveDynamicValue(value, path, context, scope) {
     if (value === undefined) {
         throw new A2uiParseError(`Missing dynamic value at ${path}`);
     }
     if (isFunctionCall(value)) {
+        if (value.call === "@index") {
+            if (scope === undefined) {
+                throw new A2uiParseError(`A2UI native adapter cannot evaluate @index outside a template at ${path}`);
+            }
+            const args = value.args === undefined ? undefined : expectObject(value.args, `${path}.args`);
+            const offset = args?.offset === undefined
+                ? 0
+                : resolveDynamicNumber(args.offset, `${path}.args.offset`, context, scope);
+            return scope.index + offset;
+        }
+        if (value.call === "formatNumber" || value.call === "formatCurrency") {
+            return resolveNumberFormat(value, path, context, scope);
+        }
+        if (value.call === "pluralize") {
+            return resolvePluralize(value, path, context, scope);
+        }
+        if (value.call === "and" || value.call === "or") {
+            return resolveBooleanList(value, path, context, scope);
+        }
+        if (value.call === "not") {
+            const args = expectObject(value.args, `${path}.args`);
+            return !resolveDynamicBoolean(args.value, `${path}.args.value`, context, scope);
+        }
+        if (value.call === "formatString") {
+            const args = expectObject(value.args, `${path}.args`);
+            const source = expectString(args.value, `${path}.args.value`);
+            const result = evaluateA2uiV1FormatString(source, (expression, index) => {
+                return resolveDynamicValue(expression, `${path}.args.value.interpolations[${index}]`, context, scope);
+            }, `${path}.args.value`, (expressionCount) => {
+                context.formatStringExpressionCount += expressionCount;
+                if (context.formatStringExpressionCount > JSON_MAX_VALUES) {
+                    throw new A2uiParseError(`Expanded A2UI native plan exceeds maximum of ${JSON_MAX_VALUES} formatString expressions`);
+                }
+            });
+            return recordFormattedString(result, path, context);
+        }
         throw new A2uiParseError(`A2UI native adapter does not execute function ${JSON.stringify(value.call)} at ${path}`);
     }
     if (isBinding(value)) {
-        const pointer = expectAbsoluteBinding(value.path, `${path}.path`);
-        return parseJsonValue(resolveJsonPointer(context.dataModel, pointer, path), path);
+        const pointer = expectString(value.path, `${path}.path`);
+        if (pointer.startsWith("/") || scope === undefined) {
+            const absolutePointer = expectAbsoluteBinding(pointer, `${path}.path`);
+            return parseJsonValue(resolveJsonPointer(context.dataModel, absolutePointer, path), path);
+        }
+        return parseJsonValue(resolveRelativePointer(scope.value, pointer, path), path);
     }
     return parseJsonValue(value, path);
 }
+function resolveDynamicNumber(value, path, context, scope) {
+    const resolved = resolveDynamicValue(value, path, context, scope);
+    if (typeof resolved !== "number" || !Number.isFinite(resolved)) {
+        throw new A2uiParseError(`Expected a finite number at ${path}`);
+    }
+    return resolved;
+}
+function resolveNumberFormat(call, path, context, scope) {
+    const args = expectObject(call.args, `${path}.args`);
+    const value = resolveDynamicNumber(args.value, `${path}.args.value`, context, scope);
+    const decimals = args.decimals === undefined
+        ? undefined
+        : parseDecimalPlaces(resolveDynamicNumber(args.decimals, `${path}.args.decimals`, context, scope), `${path}.args.decimals`);
+    const grouping = args.grouping === undefined
+        ? true
+        : resolveDynamicBoolean(args.grouping, `${path}.args.grouping`, context, scope);
+    const currency = call.call === "formatCurrency"
+        ? parseCurrencyCode(resolveDynamicString(args.currency, `${path}.args.currency`, context, scope), `${path}.args.currency`)
+        : undefined;
+    const formatter = getNumberFormat(context, decimals, grouping, currency, path);
+    try {
+        return recordFormattedString(formatter.format(value), path, context);
+    }
+    catch (cause) {
+        throw new A2uiParseError(`A2UI native adapter could not execute ${JSON.stringify(call.call)} at ${path}`, { cause });
+    }
+}
+const PLURAL_CATEGORIES = Object.freeze(["zero", "one", "two", "few", "many", "other"]);
+function resolvePluralize(call, path, context, scope) {
+    const args = expectObject(call.args, `${path}.args`);
+    const value = resolveDynamicNumber(args.value, `${path}.args.value`, context, scope);
+    const forms = new Map();
+    for (const category of PLURAL_CATEGORIES) {
+        if (args[category] !== undefined) {
+            forms.set(category, resolveDynamicString(args[category], `${path}.args.${category}`, context, scope));
+        }
+    }
+    const other = forms.get("other");
+    if (other === undefined) {
+        throw new A2uiParseError(`Missing plural fallback at ${path}.args.other`);
+    }
+    const category = getPluralRules(context, path).select(value);
+    return recordFormattedString(forms.get(category) ?? other, path, context);
+}
+function getPluralRules(context, path) {
+    const key = context.locale ?? "";
+    const cached = context.pluralRules.get(key);
+    if (cached !== undefined) {
+        return cached;
+    }
+    try {
+        if (context.locale !== undefined &&
+            Intl.PluralRules.supportedLocalesOf(context.locale, { localeMatcher: "lookup" }).length === 0) {
+            throw new A2uiParseError(`Locale ${JSON.stringify(context.locale)} does not support plural rules at ${path}`);
+        }
+        const rules = new Intl.PluralRules(context.locale, { type: "cardinal" });
+        context.pluralRules.set(key, rules);
+        return rules;
+    }
+    catch (cause) {
+        if (cause instanceof A2uiParseError) {
+            throw cause;
+        }
+        throw new A2uiParseError(`A2UI native adapter could not construct plural rules at ${path}`, {
+            cause,
+        });
+    }
+}
+function resolveBooleanList(call, path, context, scope) {
+    const args = expectObject(call.args, `${path}.args`);
+    if (!Array.isArray(args.values) || args.values.length < 2) {
+        throw new A2uiParseError(`Expected at least two boolean values at ${path}.args.values`);
+    }
+    const values = args.values.map((value, index) => resolveDynamicBoolean(value, `${path}.args.values[${index}]`, context, scope));
+    return call.call === "and" ? values.every(Boolean) : values.some(Boolean);
+}
+function parseDecimalPlaces(value, path) {
+    if (!Number.isSafeInteger(value) || value < 0 || value > 100) {
+        throw new A2uiParseError(`Expected decimal places from 0 through 100 at ${path}`);
+    }
+    return value;
+}
+function parseCurrencyCode(value, path) {
+    const currency = value.toUpperCase();
+    if (!/^[A-Z]{3}$/.test(currency) || !ISO_4217_CURRENCY_CODES.has(currency)) {
+        throw new A2uiParseError(`Expected a current ISO 4217 currency code at ${path}`);
+    }
+    return currency;
+}
+function getNumberFormat(context, decimals, grouping, currency, path) {
+    const key = JSON.stringify([
+        context.locale ?? null,
+        currency ?? null,
+        decimals ?? null,
+        grouping,
+    ]);
+    const cached = context.numberFormats.get(key);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const options = {
+        useGrouping: grouping,
+        ...(currency === undefined ? {} : { style: "currency", currency }),
+        ...(decimals === undefined
+            ? {}
+            : { minimumFractionDigits: decimals, maximumFractionDigits: decimals }),
+    };
+    try {
+        const formatter = new Intl.NumberFormat(context.locale, options);
+        context.numberFormats.set(key, formatter);
+        return formatter;
+    }
+    catch (cause) {
+        throw new A2uiParseError(`Invalid number-format options at ${path}`, { cause });
+    }
+}
+function recordFormattedString(value, path, context) {
+    if (value.length > JSON_MAX_STRING_LENGTH) {
+        throw new A2uiParseError(`A2UI formatted output at ${path} exceeds maximum length of ${JSON_MAX_STRING_LENGTH}`);
+    }
+    context.formattedStringLength += value.length;
+    if (context.formattedStringLength > A2UI_V1_MAX_SOURCE_LENGTH) {
+        throw new A2uiParseError(`Expanded A2UI native plan exceeds maximum formatted-string length of ${A2UI_V1_MAX_SOURCE_LENGTH}`);
+    }
+    return value;
+}
 function resolveJsonPointer(document, pointer, path) {
     if (pointer === "") {
         return document;
     }
+    return resolvePointerTokens(document, pointer.slice(1).split("/"), pointer, path);
+}
+function resolveRelativePointer(document, pointer, path) {
+    if (pointer === "") {
+        return document;
+    }
+    return resolvePointerTokens(document, pointer.split("/"), pointer, path);
+}
+function resolvePointerTokens(document, encodedTokens, pointer, path) {
     let cursor = document;
-    for (const encodedToken of pointer.slice(1).split("/")) {
+    for (const encodedToken of encodedTokens) {
         const token = decodePointerToken(encodedToken, pointer);
         if (Array.isArray(cursor)) {
             if (!/^(0|[1-9][0-9]*)$/.test(token)) {
@@ -251,6 +568,25 @@ function resolveJsonPointer(document, pointer, path) {
     }
     return cursor;
 }
+function resolveBindingPointer(value, path, scope) {
+    const pointer = expectString(value, path);
+    if (pointer.startsWith("/") || scope === undefined) {
+        return expectAbsoluteBinding(pointer, path);
+    }
+    return pointer === "" ? scope.pointer : `${scope.pointer}/${pointer}`;
+}
+function appendPointerToken(pointer, encodedToken) {
+    return `${pointer}/${encodedToken}`;
+}
+function appendInstanceKey(parentKey, componentId, index) {
+    // Component IDs are arbitrary strings. Escape every key delimiter, including the escape marker,
+    // so distinct component paths cannot collapse to the same renderer-only dispatch identity.
+    const encodedId = componentId
+        .replaceAll("%", "%25")
+        .replaceAll("/", "%2F")
+        .replaceAll(":", "%3A");
+    return `${parentKey}/${encodedId}:${index}`;
+}
 function expectAbsoluteBinding(value, path) {
     const pointer = expectString(value, path);
     if (pointer !== "" && !pointer.startsWith("/")) {