@reactvision/react-viro 2.57.0 → 2.57.3

package/dist/components/Studio/StudioARScene.js

@@ -51,7 +51,12 @@ const collisionBindingsRuntime_1 = require("./domain/collisionBindingsRuntime");
 const collisionPairKey_1 = require("./domain/collisionPairKey");
 const triggerImageRegistry_1 = require("./domain/triggerImageRegistry");
 const viroNodeFactory_1 = require("./domain/viroNodeFactory");
+const defaultApiRequestExecutor_1 = require("./domain/defaultApiRequestExecutor");
 const sceneNavigationHandler_1 = require("./domain/sceneNavigationHandler");
+const variableStore_1 = require("./domain/variableStore");
+const visibilityStore_1 = require("./domain/visibilityStore");
+const soundManager_1 = require("./domain/soundManager");
+const StudioSounds_1 = require("./domain/StudioSounds");
 const studioMaterials_1 = require("./domain/studioMaterials");
 const useStudioShaderTimeUniforms_1 = require("./domain/useStudioShaderTimeUniforms");
 const useStudioShaderViewportUniforms_1 = require("./domain/useStudioShaderViewportUniforms");
@@ -70,8 +75,82 @@ const StudioARScene = (props) => {
 };
 exports.StudioARScene = StudioARScene;
 const StudioARSceneInner = (props) => {
-    const { sceneNavigator, sceneData, onReady, onSceneChange } = props;
+    const { sceneNavigator, sceneData, onReady, onSceneChange, variableStore } = props;
     const { scene, assets, animations, collision_bindings, functions } = sceneData;
+    // ─── Sequence scheduler ───────────────────────────────────────────────────
+    // One per scene. Drives WAIT steps; cancelled on unmount and on navigation so
+    // a pending WAIT never fires into a torn-down or replaced scene.
+    const schedulerRef = (0, react_1.useRef)(null);
+    if (schedulerRef.current === null) {
+        schedulerRef.current = new sceneNavigationHandler_1.SequenceScheduler();
+    }
+    (0, react_1.useEffect)(() => {
+        return () => {
+            schedulerRef.current?.dispose();
+            schedulerRef.current = null;
+            // dispose() bumps the scheduler generation first; reset() then clears any
+            // pending sound backstop timers and fires their callbacks, which now
+            // no-op via the generation guard so unmount can't advance a waited step.
+            soundManagerRef.current?.reset();
+        };
+    }, []);
+    // ─── Variable store ───────────────────────────────────────────────────────
+    // Normally passed down by the navigator (session-scoped); hosts mounting this
+    // scene directly get a scene-local fallback. Seeding happens here, at instance
+    // init, so values exist before any effect dispatches on_load. seed() is
+    // initialize-if-absent, hence idempotent and strict-mode safe.
+    const variableStoreRef = (0, react_1.useRef)(null);
+    if (variableStoreRef.current === null) {
+        variableStoreRef.current = variableStore ?? new variableStore_1.StudioVariableStore();
+        variableStoreRef.current.seed(sceneData.variables ?? []);
+    }
+    // ─── Visibility store ─────────────────────────────────────────────────────
+    // Scene-scoped (asset placements are per-scene), keyed by asset id. Seeded
+    // from each asset's author-time hidden_on_load default; Set Visibility
+    // actions flip it at runtime. Re-seeded on scene change so a persisted
+    // instance doesn't carry stale visibility across a navigation.
+    const visibilityStoreRef = (0, react_1.useRef)(null);
+    if (visibilityStoreRef.current === null) {
+        visibilityStoreRef.current = new visibilityStore_1.StudioVisibilityStore();
+        visibilityStoreRef.current.seed(assets);
+    }
+    (0, react_1.useEffect)(() => {
+        visibilityStoreRef.current?.reseed(assets);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [scene.id]);
+    // ─── Sound manager ────────────────────────────────────────────────────────
+    // Per-scene. PLAY/STOP scene-function actions drive it; <StudioSounds> renders
+    // the active list. Reset on scene change so sounds don't leak across a
+    // navigation (sounds, unlike variables, are not session-scoped).
+    const soundManagerRef = (0, react_1.useRef)(null);
+    if (soundManagerRef.current === null) {
+        soundManagerRef.current = new soundManager_1.StudioSoundManager();
+    }
+    (0, react_1.useEffect)(() => {
+        soundManagerRef.current?.reset();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [scene.id]);
+    // Position for a spatial PLAY: look up the placed target asset (matches the
+    // node factory's position derivation, position_z defaulting to -2).
+    const getAssetPosition = (0, react_1.useCallback)((assetId) => {
+        const a = assets.find((x) => x.id === assetId);
+        if (!a)
+            return undefined;
+        return [a.position_x ?? 0, a.position_y ?? 0, a.position_z ?? -2];
+    }, [assets]);
+    const runtimeCtx = (0, react_1.useMemo)(() => ({
+        scheduler: schedulerRef.current,
+        variableStore: variableStoreRef.current,
+        apiRequestExecutor: defaultApiRequestExecutor_1.defaultApiRequestExecutor,
+        visibilityStore: visibilityStoreRef.current,
+        soundManager: soundManagerRef.current,
+        getAssetPosition,
+    }), [getAssetPosition]);
+    // Cancel this scene's pending WAITs before handing off to the next scene.
+    const handleSceneChange = (0, react_1.useCallback)((sceneId, sceneName) => {
+        schedulerRef.current?.cancelAll();
+        onSceneChange?.(sceneId, sceneName);
+    }, [onSceneChange]);
     // ─── Material registration ────────────────────────────────────────────────
     const materialsRegisteredRef = (0, react_1.useRef)(false);
     if (!materialsRegisteredRef.current) {
@@ -103,7 +182,10 @@ const StudioARSceneInner = (props) => {
     const triggerAnimation = (0, react_1.useCallback)((targetAssetId, animationKey) => {
         // Viro's animation prop is edge-triggered on false→true. Force false first,
         // then flip to true on the next frame so a re-trigger of the same key fires.
-        setAnimOverrides((prev) => ({ ...prev, [targetAssetId]: { key: animationKey, run: false } }));
+        setAnimOverrides((prev) => ({
+            ...prev,
+            [targetAssetId]: { key: animationKey, run: false },
+        }));
         const handle = requestAnimationFrame(() => {
             triggerHandlesRef.current.delete(handle);
             setAnimOverrides((prev) => {
@@ -148,21 +230,29 @@ const StudioARSceneInner = (props) => {
                 interruptible: activeAnim.interruptible,
                 delay: activeAnim.delay_ms ?? 0,
                 onStart: activeAnim.on_start_function
-                    ? () => (0, sceneNavigationHandler_1.executeOnLoadFunction)(activeAnim.on_start_function, functions, sceneNavigator, animations, (id, key) => triggerAnimationRef.current(id, key))
+                    ? () => (0, sceneNavigationHandler_1.executeOnLoadFunction)(activeAnim.on_start_function, functions, sceneNavigator, animations, (id, key) => triggerAnimationRef.current(id, key), handleSceneChange, runtimeCtx)
                     : undefined,
                 onFinish: activeAnim.on_finish_function
-                    ? () => (0, sceneNavigationHandler_1.executeOnLoadFunction)(activeAnim.on_finish_function, functions, sceneNavigator, animations, (id, key) => triggerAnimationRef.current(id, key))
+                    ? () => (0, sceneNavigationHandler_1.executeOnLoadFunction)(activeAnim.on_finish_function, functions, sceneNavigator, animations, (id, key) => triggerAnimationRef.current(id, key), handleSceneChange, runtimeCtx)
                     : undefined,
             };
         }
         return states;
-    }, [animations, animOverrides, loadedAssetIds, functions, sceneNavigator]);
+    }, [
+        animations,
+        animOverrides,
+        loadedAssetIds,
+        functions,
+        sceneNavigator,
+        handleSceneChange,
+        runtimeCtx,
+    ]);
     // ─── on_load_function ─────────────────────────────────────────────────────
     const onLoadExecutedRef = (0, react_1.useRef)(false);
     (0, react_1.useEffect)(() => {
         if (scene.on_load_function && !onLoadExecutedRef.current) {
             onLoadExecutedRef.current = true;
-            (0, sceneNavigationHandler_1.executeOnLoadFunction)(scene.on_load_function, functions, sceneNavigator, animations, (id, key) => triggerAnimationRef.current(id, key), onSceneChange);
+            (0, sceneNavigationHandler_1.executeOnLoadFunction)(scene.on_load_function, functions, sceneNavigator, animations, (id, key) => triggerAnimationRef.current(id, key), handleSceneChange, runtimeCtx);
         }
     }, [scene.id]);
     // ─── Collision bindings ───────────────────────────────────────────────────
@@ -188,8 +278,15 @@ const StudioARSceneInner = (props) => {
     const getCollisionHandler = (0, react_1.useCallback)((placementId) => {
         if (!collisionAssetIds.has(placementId))
             return undefined;
-        return (0, collisionBindingsRuntime_1.createPlacementCollisionHandler)(placementId, bindingsByPairKey, sceneNavigator, animations, collisionCooldownRef, (id, key) => triggerAnimationRef.current(id, key), onSceneChange);
-    }, [bindingsByPairKey, collisionAssetIds, sceneNavigator, animations]);
+        return (0, collisionBindingsRuntime_1.createPlacementCollisionHandler)(placementId, bindingsByPairKey, sceneNavigator, animations, collisionCooldownRef, (id, key) => triggerAnimationRef.current(id, key), handleSceneChange, runtimeCtx);
+    }, [
+        bindingsByPairKey,
+        collisionAssetIds,
+        sceneNavigator,
+        animations,
+        handleSceneChange,
+        runtimeCtx,
+    ]);
     // ─── Trigger image targets ────────────────────────────────────────────────
     const { planeAssets, imageTriggeredAssets } = (0, react_1.useMemo)(() => {
         const plane = assets.filter((a) => !a.trigger_image_url);
@@ -221,7 +318,9 @@ const StudioARSceneInner = (props) => {
         };
     }, [imageTriggeredAssets]);
     // ─── Ready callback ───────────────────────────────────────────────────────
-    (0, react_1.useEffect)(() => { onReady?.(); }, []);
+    (0, react_1.useEffect)(() => {
+        onReady?.();
+    }, []);
     // ─── Render helpers ───────────────────────────────────────────────────────
     const maxModels = react_native_1.Platform.OS === "android" ? ANDROID_MAX_3D_MODELS : IOS_MAX_3D_MODELS;
     const renderedPlaneAssets = (0, react_1.useMemo)(() => {
@@ -235,10 +334,20 @@ const StudioARSceneInner = (props) => {
                     return null;
                 }
             }
-            return (0, viroNodeFactory_1.createNode)(asset, sceneNavigator, animations, scene, (id, key) => triggerAnimationRef.current(id, key), animationStates, handleAssetLoaded, getCollisionHandler(asset.id), onSceneChange);
+            return (0, viroNodeFactory_1.createNode)(asset, sceneNavigator, animations, scene, (id, key) => triggerAnimationRef.current(id, key), animationStates, handleAssetLoaded, getCollisionHandler(asset.id), handleSceneChange, runtimeCtx);
         })
             .filter(Boolean);
-    }, [planeAssets, sceneNavigator, animations, animationStates, handleAssetLoaded, getCollisionHandler, maxModels, onSceneChange]);
+    }, [
+        planeAssets,
+        sceneNavigator,
+        animations,
+        animationStates,
+        handleAssetLoaded,
+        getCollisionHandler,
+        maxModels,
+        handleSceneChange,
+        runtimeCtx,
+    ]);
     const renderedImageTriggeredAssets = (0, react_1.useMemo)(() => {
         if (ViroPlatform_1.isQuest)
             return [];
@@ -247,7 +356,7 @@ const StudioARSceneInner = (props) => {
             const targetName = urlToTargetName.get(asset.trigger_image_url);
             if (!targetName)
                 return null;
-            const node = (0, viroNodeFactory_1.createNode)(asset, sceneNavigator, animations, scene, (id, key) => triggerAnimationRef.current(id, key), animationStates, handleAssetLoaded, getCollisionHandler(asset.id), onSceneChange);
+            const node = (0, viroNodeFactory_1.createNode)(asset, sceneNavigator, animations, scene, (id, key) => triggerAnimationRef.current(id, key), animationStates, handleAssetLoaded, getCollisionHandler(asset.id), handleSceneChange, runtimeCtx);
             if (!node)
                 return null;
             return (<ViroARImageMarker_1.ViroARImageMarker key={asset.id} target={targetName}>
@@ -255,7 +364,17 @@ const StudioARSceneInner = (props) => {
           </ViroARImageMarker_1.ViroARImageMarker>);
         })
             .filter(Boolean);
-    }, [urlToTargetName, imageTriggeredAssets, sceneNavigator, animations, animationStates, handleAssetLoaded, getCollisionHandler, onSceneChange]);
+    }, [
+        urlToTargetName,
+        imageTriggeredAssets,
+        sceneNavigator,
+        animations,
+        animationStates,
+        handleAssetLoaded,
+        getCollisionHandler,
+        handleSceneChange,
+        runtimeCtx,
+    ]);
     // ─── Plane detection (AR only) ────────────────────────────────────────────
     const planeDetectionMode = (scene.plane_detection ?? "NONE").toUpperCase();
     const planeAlignment = (scene.plane_direction ?? "Horizontal");
@@ -283,14 +402,22 @@ const StudioARSceneInner = (props) => {
     const physicsWorld = physicsWorldConfig?.enabled
         ? (0, physicsConfig_1.buildViroPhysicsWorld)(physicsWorldConfig)
         : undefined;
-    const physicsProps = physicsWorld ? { physicsWorld: physicsWorld } : {};
+    const physicsProps = physicsWorld
+        ? { physicsWorld: physicsWorld }
+        : {};
     // ─── Render ───────────────────────────────────────────────────────────────
     const children = (<>
       {ViroPlatform_1.isQuest && <ViroController_1.ViroController controllerVisibility reticleVisibility/>}
       <ViroAmbientLight_1.ViroAmbientLight color="#ffffff" intensity={1000}/>
       {renderAssets()}
       {renderedImageTriggeredAssets}
-      {assets.length === 0 && (<ViroText_1.ViroText text="No assets to display" position={[0, 0, -2]} style={{ fontFamily: "Arial", fontSize: 16, color: "#CCCCCC", textAlign: "center" }}/>)}
+      <StudioSounds_1.StudioSounds manager={soundManagerRef.current}/>
+      {assets.length === 0 && (<ViroText_1.ViroText text="No assets to display" position={[0, 0, -2]} style={{
+                fontFamily: "Arial",
+                fontSize: 16,
+                color: "#CCCCCC",
+                textAlign: "center",
+            }}/>)}
     </>);
     if (ViroPlatform_1.isQuest) {
         return <ViroScene_1.ViroScene {...physicsProps}>{children}</ViroScene_1.ViroScene>;

package/dist/components/Studio/StudioSceneNavigator.js

@@ -43,6 +43,7 @@ const ViroXRSceneNavigator_1 = require("../ViroXRSceneNavigator");
 const ViroPlatform_1 = require("../Utilities/ViroPlatform");
 const animationRegistry_1 = require("./domain/animationRegistry");
 const studioMaterials_1 = require("./domain/studioMaterials");
+const variableStore_1 = require("./domain/variableStore");
 const StudioARScene_1 = require("./StudioARScene");
 const VRTStudioModule_1 = require("./VRTStudioModule");
 function LoadingARScene() { return <ViroARScene_1.ViroARScene />; }
@@ -72,6 +73,18 @@ const styles = react_native_1.StyleSheet.create({
 function StudioSceneNavigator({ sceneId, worldAlignment = "Gravity", autofocus = true, style, onSceneReady, onError, onSceneChange, onExitViro, }) {
     const navigatorRef = (0, react_1.useRef)(null);
     const loadedSceneIdRef = (0, react_1.useRef)(null);
+    // Session-scoped variable store: outlives every scene push, resets when the
+    // navigator (= the AR/VR session) unmounts.
+    const variableStoreRef = (0, react_1.useRef)(null);
+    if (variableStoreRef.current === null) {
+        variableStoreRef.current = new variableStore_1.StudioVariableStore();
+    }
+    (0, react_1.useEffect)(() => {
+        return () => {
+            variableStoreRef.current?.reset();
+            variableStoreRef.current = null;
+        };
+    }, []);
     const onSceneReadyRef = (0, react_1.useRef)(onSceneReady);
     const onErrorRef = (0, react_1.useRef)(onError);
     const onSceneChangeRef = (0, react_1.useRef)(onSceneChange);
@@ -137,6 +150,7 @@ function StudioSceneNavigator({ sceneId, worldAlignment = "Gravity", autofocus =
                 sceneData,
                 onReady: onSceneReadyRef.current,
                 onSceneChange: onSceneChangeRef.current,
+                variableStore: variableStoreRef.current,
             },
         };
         if (ViroPlatform_1.isQuest) {

package/dist/components/Studio/VRTStudioModule.d.ts

@@ -12,4 +12,10 @@ export declare const VRTStudioModule: {
     rvGetProject: () => Promise<StudioModuleResult>;
     /** Returns the configured project ID, or null if not set. */
     rvGetProjectId: () => Promise<string | null>;
+    /**
+     * POSTs a pre-serialised scene-api-request body ({function_id, variables})
+     * to the egress proxy, authenticated with the app's RVApiKey. The resolved
+     * `data` is the proxy's outcome envelope JSON.
+     */
+    rvStudioApiRequest: (bodyJson: string) => Promise<StudioModuleResult>;
 };

package/dist/components/Studio/VRTStudioModule.js

@@ -28,4 +28,14 @@ exports.VRTStudioModule = {
             return Promise.resolve(null);
         return native.rvGetProjectId();
     },
+    /**
+     * POSTs a pre-serialised scene-api-request body ({function_id, variables})
+     * to the egress proxy, authenticated with the app's RVApiKey. The resolved
+     * `data` is the proxy's outcome envelope JSON.
+     */
+    rvStudioApiRequest: (bodyJson) => {
+        if (!native)
+            return Promise.resolve(NOT_AVAILABLE);
+        return native.rvStudioApiRequest(bodyJson);
+    },
 };

package/dist/components/Studio/domain/StudioSounds.d.ts

@@ -0,0 +1,11 @@
+import * as React from "react";
+import { StudioSoundManager } from "./soundManager";
+/**
+ * Renders every actively-playing sound from the manager, re-painting the whole
+ * list on any change (like the reactive variable-text nodes). Non-looping sounds
+ * remove themselves on finish; any sound removes itself on error so a clip that
+ * fails to load releases a waiting step instead of stalling the sequence.
+ */
+export declare const StudioSounds: React.FC<{
+    manager: StudioSoundManager;
+}>;

package/dist/components/Studio/domain/StudioSounds.js

@@ -0,0 +1,69 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StudioSounds = void 0;
+const React = __importStar(require("react"));
+const ViroSound_1 = require("../../ViroSound");
+const ViroSpatialSound_1 = require("../../ViroSpatialSound");
+/**
+ * Renders every actively-playing sound from the manager, re-painting the whole
+ * list on any change (like the reactive variable-text nodes). Non-looping sounds
+ * remove themselves on finish; any sound removes itself on error so a clip that
+ * fails to load releases a waiting step instead of stalling the sequence.
+ */
+const StudioSounds = ({ manager, }) => {
+    const [, force] = React.useReducer((n) => n + 1, 0);
+    React.useEffect(() => manager.subscribe(force), [manager]);
+    return (<>
+      {manager.getActive().map((s) => {
+            const shared = {
+                source: { uri: s.url },
+                volume: s.volume,
+                loop: s.loop,
+                paused: false,
+                onFinish: () => {
+                    if (!s.loop)
+                        manager.remove(s.playId);
+                },
+                onError: (e) => {
+                    console.warn(`[Studio] Sound failed: ${s.audioAssetId} (#${s.playId})`, e?.nativeEvent?.error);
+                    manager.remove(s.playId);
+                },
+            };
+            return s.position ? (<ViroSpatialSound_1.ViroSpatialSound key={s.playId} position={s.position} {...shared}/>) : (<ViroSound_1.ViroSound key={s.playId} {...shared}/>);
+        })}
+    </>);
+};
+exports.StudioSounds = StudioSounds;

package/dist/components/Studio/domain/apiRequestHelpers.d.ts

@@ -0,0 +1,180 @@
+/**
+ * API Request helpers: template validation + interpolation (URL / headers /
+ * JSON body), allowlist host matching, dot-path response extraction, and
+ * response->variable binding application. Pure logic, no platform APIs (no
+ * URL constructor — Hermes-safe), shared by the Studio editor, the
+ * scene-api-request egress proxy, and the scene runtime.
+ *
+ * Dual-maintained: this file exists in the Viro repo
+ * (components/Studio/domain/) and the ReactVisionStudio monorepo
+ * (packages/common/scene-assets/). Keep the two copies identical.
+ *
+ * Interpolation rules (fail closed — unknown or malformed placeholders are
+ * errors, never substituted with empty strings):
+ *   - Placeholders are written {{name}} where name matches the
+ *     scene_variables name constraint.
+ *   - URL: the origin (scheme://host[:port]) must be static; placeholders are
+ *     only legal after it and substitute percent-encoded.
+ *   - Headers: values substitute as strings; control characters are rejected.
+ *   - Body: the template must parse as JSON. A string value that is EXACTLY
+ *     one placeholder substitutes as the typed value (number stays number);
+ *     embedded placeholders substitute stringified; placeholders outside
+ *     string values are invalid JSON and rejected. Re-serialisation makes
+ *     structural injection impossible.
+ */
+export type ApiVariableType = "BOOLEAN" | "NUMBER" | "STRING";
+export type ApiPrimitiveValue = boolean | number | string;
+export type ApiRequestBindingSource = "BODY" | "STATUS" | "OK" | "ERROR_MESSAGE";
+export type ApiHeaderTemplate = {
+    key: string;
+    value_template: string;
+};
+export declare const API_REQUEST_TIMEOUT_MIN_MS = 1000;
+export declare const API_REQUEST_TIMEOUT_MAX_MS = 30000;
+export declare const API_REQUEST_TIMEOUT_DEFAULT_MS = 10000;
+export declare const API_REQUEST_MAX_URL_LENGTH = 2048;
+export declare const API_REQUEST_MAX_BODY_LENGTH = 65536;
+export declare const API_REQUEST_MAX_SELECTOR_LENGTH = 256;
+export declare const API_REQUEST_MAX_VARIABLES = 32;
+export declare const API_REQUEST_MAX_VARIABLE_VALUE_LENGTH = 4096;
+export declare const API_REQUEST_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE"];
+export type ApiRequestMethod = (typeof API_REQUEST_METHODS)[number];
+export type TemplateValidation = {
+    ok: true;
+    names: string[];
+} | {
+    ok: false;
+    error: string;
+};
+type Fail = {
+    ok: false;
+    error: string;
+};
+/** Names of every well-formed placeholder, in order of appearance. */
+export declare const extractPlaceholders: (template: string) => string[];
+/**
+ * A template string is valid when every "{{" / "}}" belongs to a well-formed
+ * placeholder. Malformed names ({{9x}}, {{a b}}) and stray braces are errors.
+ */
+export declare const validateTemplateString: (template: string) => TemplateValidation;
+export type ValueLookup = (name: string) => ApiPrimitiveValue | undefined;
+/**
+ * Fail-soft interpolation for display strings (alert title / message). Unlike
+ * the request templates this never errors: a well-formed {{name}} whose value
+ * is missing is left verbatim, so a stale or mistyped reference stays visible
+ * rather than blanking the field or suppressing the whole alert. Malformed
+ * braces (not a valid placeholder) are left untouched.
+ */
+export declare const interpolateDisplayTemplate: (template: string, get: ValueLookup) => string;
+export type UrlTemplateValidation = {
+    ok: true;
+    host: string;
+    port: string | null;
+    names: string[];
+} | Fail;
+/**
+ * Validates scheme + static origin (no placeholders, no userinfo, no IPv6
+ * literal) and the placeholder syntax of the whole template. Returns the
+ * pinned host (lowercase, no port) and explicit port if present.
+ */
+export declare const validateUrlTemplate: (template: string) => UrlTemplateValidation;
+export type UrlInterpolation = {
+    ok: true;
+    url: string;
+} | Fail;
+/**
+ * Substitutes placeholders percent-encoded into the path/query part. The
+ * origin is template-static by validation; the post-substitution recheck is
+ * belt-and-braces.
+ */
+export declare const interpolateUrlTemplate: (template: string, get: ValueLookup) => UrlInterpolation;
+export declare const HEADER_NAME_PATTERN: RegExp;
+export declare const isForbiddenHeaderName: (name: string) => boolean;
+export type HeadersValidation = {
+    ok: true;
+} | Fail;
+export declare const validateHeaderTemplates: (headers: ApiHeaderTemplate[], options?: {
+    reservedNames?: string[];
+}) => HeadersValidation;
+export type HeadersInterpolation = {
+    ok: true;
+    headers: {
+        key: string;
+        value: string;
+    }[];
+} | Fail;
+export declare const interpolateHeaders: (headers: ApiHeaderTemplate[], get: ValueLookup, options?: {
+    reservedNames?: string[];
+}) => HeadersInterpolation;
+export type BodyValidation = {
+    ok: true;
+    names: string[];
+} | Fail;
+/**
+ * The body template must be JSON; placeholders may only appear inside string
+ * values (a bare {{n}} outside a string is invalid JSON by construction).
+ */
+export declare const validateBodyTemplate: (template: string) => BodyValidation;
+export type BodyInterpolation = {
+    ok: true;
+    body: string;
+} | Fail;
+/**
+ * Parse -> walk -> substitute (typed for whole-placeholder strings) ->
+ * re-stringify. The serialiser guarantees escaping, so variable values can
+ * never change the JSON structure.
+ */
+export declare const interpolateJsonBody: (template: string, get: ValueLookup) => BodyInterpolation;
+/**
+ * Pattern grammar: "host.tld" or "*.host.tld", optional ":port". A pattern
+ * without a port matches the default HTTPS port only (no explicit port in the
+ * URL); a pattern with a port matches exactly that port. The wildcard matches
+ * subdomains at a label boundary, never the apex itself.
+ */
+export declare const matchHostPattern: (host: string, port: string | null, pattern: string) => boolean;
+export declare const isHostAllowlisted: (host: string, port: string | null, patterns: string[]) => boolean;
+export declare const validateSelector: (selector: string) => boolean;
+export type ExtractionResult = {
+    found: true;
+    value: unknown;
+} | {
+    found: false;
+};
+/** Walks `data.items[0].name`-style selectors. Missing path -> not found. */
+export declare const extractByPath: (value: unknown, selector: string) => ExtractionResult;
+export type ApiRequestBindingInput = {
+    source: ApiRequestBindingSource;
+    selector: string | null;
+    variable_name: string;
+    variable_type: ApiVariableType;
+};
+export type ApiRequestOutcomeInput = {
+    ok: boolean;
+    status: number | null;
+    body?: unknown;
+    error_message?: string | null;
+};
+export type CoercionResult = {
+    ok: true;
+    value: ApiPrimitiveValue;
+} | {
+    ok: false;
+};
+/** Primitive-only, lossless-ish coercion into the variable's declared type. */
+export declare const coerceBindingValue: (value: unknown, type: ApiVariableType) => CoercionResult;
+export type ApiRequestBindingWrite = {
+    name: string;
+    type: ApiVariableType;
+    value: ApiPrimitiveValue;
+};
+export type BindingApplication = {
+    writes: ApiRequestBindingWrite[];
+    warnings: string[];
+};
+/**
+ * Pure: resolves each applicable binding against the outcome and returns the
+ * variable writes plus warnings for skipped bindings (missing path, type
+ * mismatch). The caller applies writes to its variable store.
+ */
+export declare const applyBindings: (bindings: ApiRequestBindingInput[], outcome: ApiRequestOutcomeInput) => BindingApplication;
+export {};