@helpai/elements 0.30.0 → 0.31.0

package/package.json

@@ -80,5 +80,5 @@
   ],
   "type": "module",
   "types": "./index.d.ts",
-  "version": "0.30.0"
+  "version": "0.31.0"
 }

package/schema.d.ts

@@ -1,4 +1,4 @@
-export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, E as Endpoints, H as HandshakeResponse, L as Link, P as PAGE_AREA_SUGGESTIONS, f as PageContext, S as ServerConfig, b as SiteConfig, U as UserContext, W as WidgetConfig, c as WidgetConfigPartial, d as WidgetSettings, e as WidgetSettingsPartial, g as assetSchema, h as blocksConfigSchema, i as connectionConfigPartialSchema, j as connectionConfigSchema, k as cssColorSchema, l as cssLengthSchema, m as endpointsSchema, n as handshakeResponseSchema, o as linkSchema, p as localeSchema, q as pageContextSchema, s as serverConfigSchema, r as siteConfigSchema, u as userContextSchema, t as uuid7Schema, w as widgetConfigPartialSchema, v as widgetConfigSchema, x as widgetSettingsPartialSchema, y as widgetSettingsSchema } from './deployment-E-Jyc0nF.js';
+export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, E as Endpoints, H as HandshakeResponse, L as Link, P as PAGE_AREA_SUGGESTIONS, f as PageContext, S as ServerConfig, b as SiteConfig, U as UserContext, W as WidgetConfig, c as WidgetConfigPartial, d as WidgetSettings, e as WidgetSettingsPartial, g as assetSchema, h as blocksConfigSchema, i as connectionConfigPartialSchema, j as connectionConfigSchema, k as cssColorSchema, l as cssLengthSchema, m as endpointsSchema, n as handshakeResponseSchema, o as linkSchema, p as localeSchema, q as pageContextSchema, s as serverConfigSchema, r as siteConfigSchema, u as userContextSchema, t as uuid7Schema, w as widgetConfigPartialSchema, v as widgetConfigSchema, x as widgetSettingsPartialSchema, y as widgetSettingsSchema } from './deployment-DRGLrW2j.js';
 import { z } from 'zod';
 
 /**
@@ -56,9 +56,9 @@ declare const presentationSchema: z.ZodObject<{
         inset: z.ZodOptional<z.ZodString>;
         initialSize: z.ZodDefault<z.ZodEnum<{
             fullscreen: "fullscreen";
-            normal: "normal";
             expanded: "expanded";
             auto: "auto";
+            normal: "normal";
         }>>;
         autoSizeBreakpoint: z.ZodDefault<z.ZodNumber>;
     }, z.core.$loose>>;
@@ -240,9 +240,9 @@ type LauncherOptions = z.infer<typeof launcherOptionsSchema>;
 
 declare const initialSizeSchema: z.ZodEnum<{
     fullscreen: "fullscreen";
-    normal: "normal";
     expanded: "expanded";
     auto: "auto";
+    normal: "normal";
 }>;
 declare const resizeOptionsSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
@@ -269,9 +269,9 @@ declare const sizeOptionsSchema: z.ZodObject<{
     inset: z.ZodOptional<z.ZodString>;
     initialSize: z.ZodDefault<z.ZodEnum<{
         fullscreen: "fullscreen";
-        normal: "normal";
         expanded: "expanded";
         auto: "auto";
+        normal: "normal";
     }>>;
     autoSizeBreakpoint: z.ZodDefault<z.ZodNumber>;
 }, z.core.$loose>;
@@ -323,43 +323,43 @@ type FeatureFlags = z.infer<typeof featureFlagsSchema>;
  */
 
 declare const actionNameSchema: z.ZodEnum<{
+    close: "close";
     expand: "expand";
     fullscreen: "fullscreen";
     popOut: "popOut";
-    close: "close";
-    language: "language";
+    clear: "clear";
     theme: "theme";
+    language: "language";
     textSize: "textSize";
     history: "history";
-    clear: "clear";
     sound: "sound";
 }>;
 type ActionName = z.infer<typeof actionNameSchema>;
 declare const headerActionsSchema: z.ZodArray<z.ZodEnum<{
+    close: "close";
     expand: "expand";
     fullscreen: "fullscreen";
     popOut: "popOut";
-    close: "close";
-    language: "language";
+    clear: "clear";
     theme: "theme";
+    language: "language";
     textSize: "textSize";
     history: "history";
-    clear: "clear";
     sound: "sound";
 }>>;
 type HeaderActions = z.infer<typeof headerActionsSchema>;
 /** Section wrapper — `actions` list wrapped under `header` in the dashboard form. */
 declare const headerSchema: z.ZodObject<{
     actions: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        close: "close";
         expand: "expand";
         fullscreen: "fullscreen";
         popOut: "popOut";
-        close: "close";
-        language: "language";
+        clear: "clear";
         theme: "theme";
+        language: "language";
         textSize: "textSize";
         history: "history";
-        clear: "clear";
         sound: "sound";
     }>>>;
 }, z.core.$loose>;
@@ -375,33 +375,33 @@ type HeaderOptions = z.infer<typeof headerSchema>;
  */
 
 declare const feedbackEventSchema: z.ZodEnum<{
+    voiceStart: "voiceStart";
+    voiceStop: "voiceStop";
     error: "error";
     messageReceived: "messageReceived";
     messageSent: "messageSent";
-    voiceStart: "voiceStart";
-    voiceStop: "voiceStop";
 }>;
 type FeedbackEvent = z.infer<typeof feedbackEventSchema>;
 declare const soundOptionsSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
     volume: z.ZodDefault<z.ZodNumber>;
     events: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        voiceStart: "voiceStart";
+        voiceStop: "voiceStop";
         error: "error";
         messageReceived: "messageReceived";
         messageSent: "messageSent";
-        voiceStart: "voiceStart";
-        voiceStop: "voiceStop";
     }> & z.core.$partial, z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>>;
 }, z.core.$loose>;
 type SoundOptions = z.infer<typeof soundOptionsSchema>;
 declare const hapticsOptionsSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
     events: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        voiceStart: "voiceStart";
+        voiceStop: "voiceStop";
         error: "error";
         messageReceived: "messageReceived";
         messageSent: "messageSent";
-        voiceStart: "voiceStart";
-        voiceStop: "voiceStop";
     }> & z.core.$partial, z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodArray<z.ZodNumber>]>>>;
 }, z.core.$loose>;
 type HapticsOptions = z.infer<typeof hapticsOptionsSchema>;
@@ -410,21 +410,21 @@ declare const feedbackSchema: z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         volume: z.ZodDefault<z.ZodNumber>;
         events: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+            voiceStart: "voiceStart";
+            voiceStop: "voiceStop";
             error: "error";
             messageReceived: "messageReceived";
             messageSent: "messageSent";
-            voiceStart: "voiceStart";
-            voiceStop: "voiceStop";
         }> & z.core.$partial, z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>>;
     }, z.core.$loose>>;
     haptics: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         events: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+            voiceStart: "voiceStart";
+            voiceStop: "voiceStop";
             error: "error";
             messageReceived: "messageReceived";
             messageSent: "messageSent";
-            voiceStart: "voiceStart";
-            voiceStop: "voiceStop";
         }> & z.core.$partial, z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodArray<z.ZodNumber>]>>>;
     }, z.core.$loose>>;
 }, z.core.$loose>;
@@ -624,6 +624,48 @@ declare const formConditionSchema: z.ZodObject<{
     maxMessages: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>;
 type FormCondition = z.infer<typeof formConditionSchema>;
+/**
+ * Per-locale overrides of a form's HUMAN-FACING strings only. Structure (field
+ * `name` / `type` / `validation`, option `value`) is shared across locales and
+ * stays canonical — a translation matches the canonical form by the stable
+ * `name` (field) / `value` (option) keys; absent strings fall back to the
+ * top-level (defaultLocale) copy. The data module trims `translations` to the
+ * requested `?locale=` (≤1 entry); the widget overlays it (`overlayFormDef`).
+ */
+declare const fieldOptionTranslationSchema: z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+declare const formFieldTranslationSchema: z.ZodObject<{
+    name: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    placeholder: z.ZodOptional<z.ZodString>;
+    validationHint: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+declare const formTranslationSchema: z.ZodObject<{
+    locale: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    submitLabel: z.ZodOptional<z.ZodString>;
+    fields: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        placeholder: z.ZodOptional<z.ZodString>;
+        validationHint: z.ZodOptional<z.ZodString>;
+        options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            label: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+type FormTranslation = z.infer<typeof formTranslationSchema>;
 declare const formDefSchema: z.ZodObject<{
     id: z.ZodString;
     on: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
@@ -682,6 +724,24 @@ declare const formDefSchema: z.ZodObject<{
     mirrorToContext: z.ZodDefault<z.ZodBoolean>;
     reopenable: z.ZodDefault<z.ZodBoolean>;
     reviewable: z.ZodDefault<z.ZodBoolean>;
+    defaultLocale: z.ZodOptional<z.ZodString>;
+    translations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        locale: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        submitLabel: z.ZodOptional<z.ZodString>;
+        fields: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            label: z.ZodOptional<z.ZodString>;
+            placeholder: z.ZodOptional<z.ZodString>;
+            validationHint: z.ZodOptional<z.ZodString>;
+            options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                value: z.ZodString;
+                label: z.ZodOptional<z.ZodString>;
+                description: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>>;
 }, z.core.$loose>;
 type FormDef = z.infer<typeof formDefSchema>;
 declare const formsSchema: z.ZodArray<z.ZodObject<{
@@ -742,6 +802,24 @@ declare const formsSchema: z.ZodArray<z.ZodObject<{
     mirrorToContext: z.ZodDefault<z.ZodBoolean>;
     reopenable: z.ZodDefault<z.ZodBoolean>;
     reviewable: z.ZodDefault<z.ZodBoolean>;
+    defaultLocale: z.ZodOptional<z.ZodString>;
+    translations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        locale: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        submitLabel: z.ZodOptional<z.ZodString>;
+        fields: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            label: z.ZodOptional<z.ZodString>;
+            placeholder: z.ZodOptional<z.ZodString>;
+            validationHint: z.ZodOptional<z.ZodString>;
+            options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                value: z.ZodString;
+                label: z.ZodOptional<z.ZodString>;
+                description: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>>;
 }, z.core.$loose>>;
 type Forms = z.infer<typeof formsSchema>;
 
@@ -781,18 +859,18 @@ type I18nOptions = z.infer<typeof i18nSchema>;
  */
 
 declare const moduleLayoutSchema: z.ZodEnum<{
+    home: "home";
     chat: "chat";
     help: "help";
-    home: "home";
     news: "news";
 }>;
 type ModuleLayout = z.infer<typeof moduleLayoutSchema>;
 declare const moduleSchema: z.ZodObject<{
     label: z.ZodString;
     layout: z.ZodEnum<{
+        home: "home";
         chat: "chat";
         help: "help";
-        home: "home";
         news: "news";
     }>;
     contentTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -818,9 +896,9 @@ type ModuleOptions = z.infer<typeof moduleSchema>;
 declare const modulesSchema: z.ZodArray<z.ZodObject<{
     label: z.ZodString;
     layout: z.ZodEnum<{
+        home: "home";
         chat: "chat";
         help: "help";
-        home: "home";
         news: "news";
     }>;
     contentTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -902,4 +980,4 @@ declare const ALL_MODES: readonly Mode[];
  */
 declare function emitJsonSchema(): unknown;
 
-export { ALL_MODES, type ActionName, type AttachmentLimits, type Behavior, type CalloutPosition, type CalloutShape, type ComposerOptions, type FeatureFlags, type FeedbackEvent, type FeedbackOptions, type FieldOption, type FieldType, type FieldValidation, type FooterOptions, type FormCondition, type FormDef, type FormField, type Forms, type HapticsOptions, type HeaderActions, type HeaderOptions, type I18nOptions, type LauncherCallout, type LauncherOptions, type LauncherSize, type LauncherVariant, type Mode, type ModuleLayout, type ModuleOptions, type ModulesOptions, type Position, type PoweredBy, type Presentation, type ResizeOptions, type ResponseMode, type SendButtonOptions, type SizeOptions, type SoundOptions, type StringsOverride, type ThemeOverrides, type ThemePreference, type TrackingSettings, type VoiceMode, actionNameSchema, attachmentLimitsSchema, behaviorSchema, calloutPositionSchema, calloutShapeSchema, composerOptionsSchema, emitJsonSchema, featureFlagsSchema, feedbackEventSchema, feedbackSchema, fieldOptionSchema, fieldTypeSchema, fieldValidationSchema, footerSchema, formConditionSchema, formDefSchema, formFieldSchema, formTriggerSchema, formsSchema, hapticsOptionsSchema, headerActionsSchema, headerSchema, i18nSchema, initialSizeSchema, launcherCalloutSchema, launcherOptionsSchema, launcherSizeSchema, launcherVariantSchema, modeSchema, moduleLayoutSchema, moduleSchema, modulesSchema, positionSchema, poweredBySchema, presentationSchema, resizeOptionsSchema, responseModeSchema, sendButtonIconSchema, sendButtonOptionsSchema, sendButtonShapeSchema, sendButtonVariantSchema, sizeOptionsSchema, soundOptionsSchema, stringsOverrideSchema, themeFieldSchema, themeOverridesSchema, themePreferenceSchema, toolRefSchema, trackingSchema, voiceModeSchema, widgetSettingsSchemaForMode };
+export { ALL_MODES, type ActionName, type AttachmentLimits, type Behavior, type CalloutPosition, type CalloutShape, type ComposerOptions, type FeatureFlags, type FeedbackEvent, type FeedbackOptions, type FieldOption, type FieldType, type FieldValidation, type FooterOptions, type FormCondition, type FormDef, type FormField, type FormTranslation, type Forms, type HapticsOptions, type HeaderActions, type HeaderOptions, type I18nOptions, type LauncherCallout, type LauncherOptions, type LauncherSize, type LauncherVariant, type Mode, type ModuleLayout, type ModuleOptions, type ModulesOptions, type Position, type PoweredBy, type Presentation, type ResizeOptions, type ResponseMode, type SendButtonOptions, type SizeOptions, type SoundOptions, type StringsOverride, type ThemeOverrides, type ThemePreference, type TrackingSettings, type VoiceMode, actionNameSchema, attachmentLimitsSchema, behaviorSchema, calloutPositionSchema, calloutShapeSchema, composerOptionsSchema, emitJsonSchema, featureFlagsSchema, feedbackEventSchema, feedbackSchema, fieldOptionSchema, fieldOptionTranslationSchema, fieldTypeSchema, fieldValidationSchema, footerSchema, formConditionSchema, formDefSchema, formFieldSchema, formFieldTranslationSchema, formTranslationSchema, formTriggerSchema, formsSchema, hapticsOptionsSchema, headerActionsSchema, headerSchema, i18nSchema, initialSizeSchema, launcherCalloutSchema, launcherOptionsSchema, launcherSizeSchema, launcherVariantSchema, modeSchema, moduleLayoutSchema, moduleSchema, modulesSchema, positionSchema, poweredBySchema, presentationSchema, resizeOptionsSchema, responseModeSchema, sendButtonIconSchema, sendButtonOptionsSchema, sendButtonShapeSchema, sendButtonVariantSchema, sizeOptionsSchema, soundOptionsSchema, stringsOverrideSchema, themeFieldSchema, themeOverridesSchema, themePreferenceSchema, toolRefSchema, trackingSchema, voiceModeSchema, widgetSettingsSchemaForMode };

package/schema.json

@@ -628,7 +628,7 @@
               "properties": {
                 "text": {
                   "default": "👋 Hi! Need any help?",
-                  "description": "The message to show in the bubble. Defaults to a friendly greeting; replace with your own copy (e.g. 'Click here →' or 'Try our new feature!').",
+                  "description": "The message to show in the bubble. Defaults to a friendly greeting; replace with your own copy (e.g. 'Click here →'). May also be an i18n key (e.g. `launcherCallout`) resolved against `i18n.strings` for per-locale copy; a non-key literal renders as-is.",
                   "type": "string",
                   "minLength": 1,
                   "maxLength": 500
@@ -1590,6 +1590,104 @@
                 "default": true,
                 "description": "Submitted marker expands in place to a read-only list of the visitor's answers. Set `false` for sensitive answers that shouldn't linger on screen.",
                 "type": "boolean"
+              },
+              "defaultLocale": {
+                "description": "BCP-47 locale the top-level strings (title / fields copy) are authored in.",
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 35
+              },
+              "translations": {
+                "description": "Per-locale string overrides — the data module trims to the bootstrap `?locale=` (≤1); the widget overlays it onto the default copy.",
+                "maxItems": 50,
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "locale": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 35,
+                      "description": "BCP-47 locale tag (e.g. `en`, `fr-CA`, `zh-Hant-HK`)."
+                    },
+                    "title": {
+                      "type": "string",
+                      "maxLength": 120
+                    },
+                    "description": {
+                      "type": "string",
+                      "maxLength": 500
+                    },
+                    "submitLabel": {
+                      "type": "string",
+                      "maxLength": 60
+                    },
+                    "fields": {
+                      "maxItems": 50,
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "name": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 80,
+                            "description": "The canonical field `name` this localizes."
+                          },
+                          "label": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 200
+                          },
+                          "placeholder": {
+                            "type": "string",
+                            "maxLength": 200
+                          },
+                          "validationHint": {
+                            "type": "string",
+                            "maxLength": 280
+                          },
+                          "options": {
+                            "maxItems": 50,
+                            "type": "array",
+                            "items": {
+                              "type": "object",
+                              "properties": {
+                                "value": {
+                                  "type": "string",
+                                  "minLength": 1,
+                                  "maxLength": 200,
+                                  "description": "The canonical option `value` this localizes."
+                                },
+                                "label": {
+                                  "type": "string",
+                                  "minLength": 1,
+                                  "maxLength": 200
+                                },
+                                "description": {
+                                  "type": "string",
+                                  "maxLength": 280
+                                }
+                              },
+                              "required": [
+                                "value"
+                              ],
+                              "additionalProperties": {}
+                            }
+                          }
+                        },
+                        "required": [
+                          "name"
+                        ],
+                        "additionalProperties": {}
+                      }
+                    }
+                  },
+                  "required": [
+                    "locale"
+                  ],
+                  "additionalProperties": {}
+                }
               }
             },
             "required": [
@@ -2395,7 +2493,7 @@
                   "properties": {
                     "text": {
                       "default": "👋 Hi! Need any help?",
-                      "description": "The message to show in the bubble. Defaults to a friendly greeting; replace with your own copy (e.g. 'Click here →' or 'Try our new feature!').",
+                      "description": "The message to show in the bubble. Defaults to a friendly greeting; replace with your own copy (e.g. 'Click here →'). May also be an i18n key (e.g. `launcherCallout`) resolved against `i18n.strings` for per-locale copy; a non-key literal renders as-is.",
                       "type": "string",
                       "minLength": 1,
                       "maxLength": 500

package/schema.mjs

@@ -171,7 +171,7 @@ var calloutShapeSchema = z6.enum(["pill", "bubble", "callout"]);
 var calloutPositionSchema = z6.enum(["auto", "horizontal", "vertical"]);
 var launcherCalloutSchema = z6.object({
   text: z6.string().min(1).max(500).default("\u{1F44B} Hi! Need any help?").describe(
-    "The message to show in the bubble. Defaults to a friendly greeting; replace with your own copy (e.g. 'Click here \u2192' or 'Try our new feature!')."
+    "The message to show in the bubble. Defaults to a friendly greeting; replace with your own copy (e.g. 'Click here \u2192'). May also be an i18n key (e.g. `launcherCallout`) resolved against `i18n.strings` for per-locale copy; a non-key literal renders as-is."
   ),
   shape: calloutShapeSchema.default("pill").describe("Visual shape \u2014 `pill` (slim label + arrow), `bubble` (speech-bubble tail), `callout` (loud variant)."),
   position: calloutPositionSchema.default("auto").describe(
@@ -417,6 +417,25 @@ var formConditionSchema = z12.object({
   minMessages: z12.number().int().min(0).max(1e3).optional(),
   maxMessages: z12.number().int().min(0).max(1e3).optional()
 }).loose();
+var fieldOptionTranslationSchema = z12.object({
+  value: z12.string().min(1).max(200).describe("The canonical option `value` this localizes."),
+  label: z12.string().min(1).max(200).optional(),
+  description: z12.string().max(280).optional()
+}).loose();
+var formFieldTranslationSchema = z12.object({
+  name: z12.string().min(1).max(80).describe("The canonical field `name` this localizes."),
+  label: z12.string().min(1).max(200).optional(),
+  placeholder: z12.string().max(200).optional(),
+  validationHint: z12.string().max(280).optional(),
+  options: z12.array(fieldOptionTranslationSchema).max(50).optional()
+}).loose();
+var formTranslationSchema = z12.object({
+  locale: localeSchema,
+  title: z12.string().max(120).optional(),
+  description: z12.string().max(500).optional(),
+  submitLabel: z12.string().max(60).optional(),
+  fields: z12.array(formFieldTranslationSchema).max(50).optional()
+}).loose();
 var formDefSchema = z12.object({
   id: z12.string().min(1).max(80).describe("Stable id \u2014 persistence dedupe + `manual` openForm(id)."),
   on: z12.union([formTriggerSchema, z12.array(formTriggerSchema).min(1).max(8)]).describe("Trigger(s) that surface this form."),
@@ -435,6 +454,10 @@ var formDefSchema = z12.object({
   ),
   reviewable: z12.boolean().default(true).describe(
     "Submitted marker expands in place to a read-only list of the visitor's answers. Set `false` for sensitive answers that shouldn't linger on screen."
+  ),
+  defaultLocale: localeSchema.optional().describe("BCP-47 locale the top-level strings (title / fields copy) are authored in."),
+  translations: z12.array(formTranslationSchema).max(50).optional().describe(
+    "Per-locale string overrides \u2014 the data module trims to the bootstrap `?locale=` (\u22641); the widget overlays it onto the default copy."
   )
 }).loose();
 var formsSchema = z12.array(formDefSchema).max(20).describe(
@@ -871,12 +894,15 @@ export {
   feedbackEventSchema,
   feedbackSchema,
   fieldOptionSchema,
+  fieldOptionTranslationSchema,
   fieldTypeSchema,
   fieldValidationSchema,
   footerSchema,
   formConditionSchema,
   formDefSchema,
   formFieldSchema,
+  formFieldTranslationSchema,
+  formTranslationSchema,
   formTriggerSchema,
   formsSchema,
   handshakeResponseSchema,

package/web-component.d.ts

@@ -3,16 +3,22 @@
  *
  * Attributes mirror {@link ChatWidgetOptions} (kebab-cased: `public-key`,
  * `ai-agent-deployment-id`, `mode`, `theme`, `base-url`, …). Reactive
- * attributes trigger a re-mount when they change at runtime — see
+ * attributes trigger a re-resolve when they change at runtime — see
  * {@link REACTIVE_ATTRS}.
  *
  * Mode resolution: the tag itself doesn't pin a default mode. When no
  * `mode=…` attribute is set, the resolver default (`"floating"`) seeds
  * the very first frame — which the App's handshake gate keeps blank
- * — then the server's pushed `widget.presentation.mode` wins via
- * `mergeServerConfig` (subscribed in `boot()` below). Drop a bare
- * `<web-ai-chat public-key="…" ai-agent-deployment-id="…">` on the
- * page and the deployment's dashboard config drives the layout.
+ * — then the server's pushed `widget.presentation.mode` wins via the
+ * shared runtime's handshake merge. Drop a bare `<web-ai-chat
+ * public-key="…" ai-agent-deployment-id="…">` on the page and the
+ * deployment's dashboard config drives the layout.
+ *
+ * Everything between `<App>` and the shadow host — the ErrorBoundary, the
+ * handshake-config merge, the usage tracker, host-attribute application — lives
+ * in the shared {@link createWidgetRuntime} that `mount()` (`src/index.ts`) also
+ * uses, so the two boot paths can't drift. This file owns only what's specific
+ * to the custom element: attribute parsing and the connect/disconnect lifecycle.
  */
 declare function registerWebComponent(): void;