@gamaro.io/core-types 0.6.0

package/LICENSE

@@ -0,0 +1,48 @@
+Versiq Core Types — Commercial Source-available License
+========================================================
+
+Copyright (c) 2024-2026 Sébastien Dolard
+
+This package ships TypeScript type contracts and Zod schemas consumed by the
+Versiq Widget SDK. It is published under the same license as the widget
+bundle so that TypeScript integrators get a working type tree when they
+install `@gamaro.io/widget`.
+
+1. Permitted use
+   You may, without separate written agreement:
+   (a) Install this package as a transitive dependency of
+       `@gamaro.io/widget` via standard package managers.
+   (b) Import the exported types and Zod schemas in client-side or
+       server-side code that interoperates with the Versiq backend API.
+
+2. Prohibited without prior written agreement
+   You may not, in whole or in part:
+   (a) Modify, fork, or create derivative works for redistribution under
+       any name.
+   (b) Redistribute the package, or any derivative, under a different
+       package name, namespace, or scope.
+   (c) Use these contracts to design or implement a competing widget SDK,
+       qualification backend, or conversation orchestration product.
+   (d) Remove, alter, or obscure copyright notices, attribution, or this
+       license file from any copy.
+
+3. Production use
+   Use of the corresponding Versiq backend in production is subject to the
+   Versiq Commercial Terms of Service. The license granted here is for the
+   type contracts only; it does not authorize backend access.
+
+4. No warranty
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+   OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
+   IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+   CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+   TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+   SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+5. Termination
+   Any breach of section 2 terminates your rights under section 1
+   immediately, without notice, and you must cease all use of the software
+   and destroy all copies in your possession or control.
+
+For commercial licensing or written-agreement inquiries: admin@dolard.eu

package/README.md

@@ -0,0 +1,104 @@
+# @gamaro.io/core-types
+
+Cross-workspace TypeScript contracts and Zod schemas consumed by
+[`@gamaro.io/widget`](https://www.npmjs.com/package/@gamaro.io/widget).
+
+> **Companion package — not for standalone use.** This package exists to share
+> type definitions between the Versiq backend, the marketing site, and the
+> public widget SDK. If you are integrating the widget into your site, you need
+> [`@gamaro.io/widget`](https://www.npmjs.com/package/@gamaro.io/widget), not
+> this one. The widget already re-exports the types you need.
+
+## When you might need this directly
+
+You only need to depend on `@gamaro.io/core-types` if you are building a custom
+integration that talks to the Versiq backend without going through the widget
+SDK — for example, a server-to-server pipeline that posts events to the Versiq
+API and wants the same Zod schemas the official widget uses.
+
+## Installation
+
+```bash
+npm install @gamaro.io/core-types zod
+# or
+pnpm add @gamaro.io/core-types zod
+```
+
+`zod` is a peer dependency: schemas are runtime-validatable.
+
+## Scope (ADR-006)
+
+The package contract is intentionally narrow: only types and schemas that cross
+a workspace boundary live here. Domain-specific schemas (real-estate profiles,
+B2B qualification, scoring rules, …) stay in the workspace that owns the domain.
+
+## Public exports
+
+| Module                  | Contents                                                                 |
+| ----------------------- | ------------------------------------------------------------------------ |
+| `theme`                 | `ThemeConfig`, hex-color constraints, default palette                    |
+| `theme-resolver`        | Merges host-side theme with server-side theme; returns the final config  |
+| `viewport`              | Viewport bucket helpers (`mobile` / `tablet` / `desktop`) + breakpoints  |
+| `widget-config`         | `WidgetConfig` — the public contract of `createWidget(config)`           |
+| `widget-runtime-config` | Internal runtime view of the resolved widget config (after server merge) |
+| `application-config`    | Server-side Agent metadata (vertical, allowed origins, identity)         |
+| `postmessage`           | Discriminated unions for `window.postMessage` host ↔ iframe protocol     |
+| `geo`                   | Lightweight geo primitives (`LatLng`, `BoundingBox`)                     |
+
+```typescript
+import type {
+  ThemeConfig,
+  WidgetConfig,
+  ViewportBucket,
+  HostToWidgetMessage,
+  WidgetToHostMessage,
+} from "@gamaro.io/core-types";
+
+import {
+  themeConfigSchema,
+  hostToWidgetMessageSchema,
+} from "@gamaro.io/core-types";
+```
+
+### Subpath-only modules
+
+Some helpers are exposed on a **dedicated subpath**, deliberately kept out of
+the barrel above so they carry no `zod` dependency (import them directly, not
+from the package root):
+
+| Subpath    | Contents                                                                      |
+| ---------- | ----------------------------------------------------------------------------- |
+| `/session` | `getSessionCookieName`, `isValidSessionId` — pure session cookie / id helpers |
+
+```typescript
+import {
+  getSessionCookieName,
+  isValidSessionId,
+} from "@gamaro.io/core-types/session";
+```
+
+All schemas are Zod 4 (`zod@^4.2.0`) and infer their TypeScript types via
+`z.infer<typeof xxxSchema>` — the same `.parse()` / `.safeParse()` API as the
+widget itself.
+
+## Versioning
+
+Released in lockstep with `@gamaro.io/widget` (same version number). Breaking
+changes follow SemVer:
+
+- **MINOR** — added optional fields, added discriminant values, new schemas
+- **MAJOR** — removed/renamed fields, narrowed unions, schema-level breaking
+  changes
+
+The widget SDK pins its dependency on `@gamaro.io/core-types` to the exact same
+version it ships with — you never need to align them yourself.
+
+## License
+
+Commercial Source-available — see [LICENSE](./LICENSE).
+
+This is **not** an open-source release. The source is published so integrators
+can audit what runs in their visitors' browsers, but fork / redistribution /
+competing-SDK use are prohibited without a written agreement.
+
+For commercial licensing inquiries: admin@dolard.eu

package/dist/application-config.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Application bootstrap config returned by `GET /api/application/config`.
+ *
+ * The app (`apps/app`) produces this response through a stricter server-side
+ * whitelist schema (`publicApplicationConfigSchema` in the route), and the
+ * widget (`@gamaro.io/widget`) consumes it here. Keeping the widget-side Zod
+ * schema as the canonical shape prevents drift — the server schema MUST remain
+ * a compatible subset (it may be stricter, never more permissive).
+ */
+import { z } from "zod";
+export declare const applicationConfigResponseSchema: z.ZodObject<{
+    applicationId: z.ZodString;
+    applicationSlug: z.ZodString;
+    applicationName: z.ZodString;
+    vertical: z.ZodString;
+    theme: z.ZodNullable<z.ZodObject<{
+        primaryColor: z.ZodOptional<z.ZodString>;
+        backgroundColor: z.ZodOptional<z.ZodString>;
+        textColor: z.ZodOptional<z.ZodString>;
+        borderRadius: z.ZodOptional<z.ZodNumber>;
+        fontFamily: z.ZodOptional<z.ZodString>;
+        colorScheme: z.ZodOptional<z.ZodEnum<{
+            light: "light";
+            dark: "dark";
+            auto: "auto";
+        }>>;
+    }, z.core.$strip>>;
+    allowedOrigins: z.ZodArray<z.ZodString>;
+    monitoring: z.ZodBoolean;
+    primaryObjective: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+        label: z.ZodString;
+        ctaLabel: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    identityVerificationRequired: z.ZodBoolean;
+    widget: z.ZodNullable<z.ZodObject<{
+        theme: z.ZodOptional<z.ZodObject<{
+            primaryColor: z.ZodOptional<z.ZodString>;
+            backgroundColor: z.ZodOptional<z.ZodString>;
+            textColor: z.ZodOptional<z.ZodString>;
+            borderRadius: z.ZodOptional<z.ZodNumber>;
+            fontFamily: z.ZodOptional<z.ZodString>;
+            colorScheme: z.ZodOptional<z.ZodEnum<{
+                light: "light";
+                dark: "dark";
+                auto: "auto";
+            }>>;
+        }, z.core.$strip>>;
+        position: z.ZodOptional<z.ZodEnum<{
+            "bottom-right": "bottom-right";
+            "bottom-left": "bottom-left";
+            inline: "inline";
+        }>>;
+        language: z.ZodOptional<z.ZodString>;
+        showProfile: z.ZodOptional<z.ZodBoolean>;
+        open: z.ZodOptional<z.ZodBoolean>;
+        brand: z.ZodOptional<z.ZodObject<{
+            title: z.ZodOptional<z.ZodString>;
+            avatarUrl: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strip>;
+export type ApplicationConfigResponse = z.infer<typeof applicationConfigResponseSchema>;

package/dist/application-config.js

@@ -0,0 +1,45 @@
+/**
+ * Application bootstrap config returned by `GET /api/application/config`.
+ *
+ * The app (`apps/app`) produces this response through a stricter server-side
+ * whitelist schema (`publicApplicationConfigSchema` in the route), and the
+ * widget (`@gamaro.io/widget`) consumes it here. Keeping the widget-side Zod
+ * schema as the canonical shape prevents drift — the server schema MUST remain
+ * a compatible subset (it may be stricter, never more permissive).
+ */
+import { z } from "zod";
+import { themeConfigSchema } from "./theme";
+import { widgetRuntimeConfigSchema } from "./widget-runtime-config";
+export const applicationConfigResponseSchema = z.object({
+    applicationId: z.string().uuid().describe("Application UUID"),
+    applicationSlug: z
+        .string()
+        .max(100)
+        .describe("Application slug (kebab-case)"),
+    applicationName: z.string().max(200).describe("Application display name"),
+    vertical: z
+        .string()
+        .max(50)
+        .describe("Vertical resolved from Application config"),
+    theme: themeConfigSchema.nullable().describe("Application theme"),
+    allowedOrigins: z
+        .array(z.string().max(200))
+        .max(50)
+        .describe("Allowed origins for this application"),
+    monitoring: z.boolean().describe("Monitoring enabled flag"),
+    primaryObjective: z
+        .object({
+        id: z.string().uuid(),
+        type: z.string(),
+        label: z.string(),
+        ctaLabel: z.string().nullable(),
+    })
+        .nullable()
+        .describe("Primary conversion objective"),
+    identityVerificationRequired: z
+        .boolean()
+        .describe("Whether HMAC identity verification is required"),
+    widget: widgetRuntimeConfigSchema
+        .nullable()
+        .describe("Admin-configured widget runtime config (theme, position, language, showProfile, open). Null when the application has not yet persisted a widget_config JSONB."),
+});

package/dist/geo.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Geographic cross-boundary type contracts.
+ *
+ * Cross-boundary contract shared by the geo package (`@versiq/geo`) and the
+ * app host (`apps/app`). Previously co-located in `apps/app/src/lib/ai/schemas/`
+ * by historical happenstance — directions cardinales are not AI-specific, they
+ * are pure geographic primitives.
+ */
+import { z } from "zod";
+/**
+ * Cardinal directions for directional zone search (e.g., "nord de Lyon").
+ * Uses English keys for LLM consistency, mapped to French for display.
+ */
+export declare const cardinalDirectionEnum: z.ZodEnum<{
+    north: "north";
+    northeast: "northeast";
+    east: "east";
+    southeast: "southeast";
+    south: "south";
+    southwest: "southwest";
+    west: "west";
+    northwest: "northwest";
+}>;
+export type CardinalDirection = z.infer<typeof cardinalDirectionEnum>;

package/dist/geo.js

@@ -0,0 +1,25 @@
+/**
+ * Geographic cross-boundary type contracts.
+ *
+ * Cross-boundary contract shared by the geo package (`@versiq/geo`) and the
+ * app host (`apps/app`). Previously co-located in `apps/app/src/lib/ai/schemas/`
+ * by historical happenstance — directions cardinales are not AI-specific, they
+ * are pure geographic primitives.
+ */
+import { z } from "zod";
+/**
+ * Cardinal directions for directional zone search (e.g., "nord de Lyon").
+ * Uses English keys for LLM consistency, mapped to French for display.
+ */
+export const cardinalDirectionEnum = z
+    .enum([
+    "north",
+    "northeast",
+    "east",
+    "southeast",
+    "south",
+    "southwest",
+    "west",
+    "northwest",
+])
+    .describe("Direction cardinale (north/south/east/west + combinaisons)");

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @gamaro.io/core-types
+ *
+ * Cross-workspace type contracts shared by `apps/app`, `apps/marketing` and
+ * `packages/widget`. Scope is intentionally narrow (ADR-006): only types that
+ * cross a workspace boundary live here. Do NOT dump domain-specific schemas
+ * in this package — keep them in the consumer that owns the domain.
+ *
+ * See `docs/adr/ADR-006-monorepo-package-strategy.md`.
+ */
+export * from "./motion";
+export * from "./theme";
+export * from "./theme-resolver";
+export * from "./viewport";
+export * from "./widget-config";
+export * from "./widget-runtime-config";
+export * from "./application-config";
+export * from "./postmessage";
+export * from "./geo";

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * @gamaro.io/core-types
+ *
+ * Cross-workspace type contracts shared by `apps/app`, `apps/marketing` and
+ * `packages/widget`. Scope is intentionally narrow (ADR-006): only types that
+ * cross a workspace boundary live here. Do NOT dump domain-specific schemas
+ * in this package — keep them in the consumer that owns the domain.
+ *
+ * See `docs/adr/ADR-006-monorepo-package-strategy.md`.
+ */
+export * from "./motion";
+export * from "./theme";
+export * from "./theme-resolver";
+export * from "./viewport";
+export * from "./widget-config";
+export * from "./widget-runtime-config";
+export * from "./application-config";
+export * from "./postmessage";
+export * from "./geo";

package/dist/motion.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Canonical motion tokens for the Versiq widget — the single source of truth
+ * for animation durations, easing curves and stagger timing across BOTH widget
+ * bundles (the vanilla loader in `packages/widget` and the React embed in
+ * `apps/app/src/app/widget/embed`).
+ *
+ * **This module MUST stay free of any import** (no Zod, no sibling types). It is
+ * consumed by the loader through the dedicated subpath export
+ * `@gamaro.io/core-types/motion`, which guarantees the loader's UMD
+ * bundle never pulls in Zod via the barrel `index.ts`. Adding an import here
+ * would break that guarantee.
+ *
+ * Design rationale (see `docs/adr/ADR-018-widget-motion-design.md`):
+ * - Durations follow a harmonic scale; all UI transitions stay <= 400ms so the
+ *   interaction is perceived as instant (Doherty threshold, IBM 1982).
+ * - Easing curves are Material-3-style: entering elements decelerate (`enter`),
+ *   leaving elements accelerate (`exit`), in-place motion uses `standard`. The
+ *   "soft" feel comes from deceleration at the end of travel — never `linear`
+ *   nor a steep `ease-in-out` for UI transitions.
+ */
+/**
+ * Harmonic duration scale in milliseconds.
+ * - `instant` — no animation (reduced-motion fallback, snap states).
+ * - `fast` — micro-interactions (hover, focus).
+ * - `base` — standard transitions (fades, bubble entrances).
+ * - `slow` — panels, container resize, collapses.
+ * - `slower` — looping loaders (bounce/typing dots).
+ */
+export declare const MOTION_DURATIONS: {
+    readonly instant: 0;
+    readonly fast: 150;
+    readonly base: 250;
+    readonly slow: 400;
+    readonly slower: 600;
+};
+/**
+ * Named easing curves. `standard` for in-place motion, `enter` for elements
+ * arriving (decelerate), `exit` for elements leaving (accelerate), `emphasized`
+ * for prominent panel transitions.
+ */
+export declare const MOTION_EASINGS: {
+    readonly standard: "cubic-bezier(0.4, 0, 0.2, 1)";
+    readonly enter: "cubic-bezier(0, 0, 0.2, 1)";
+    readonly exit: "cubic-bezier(0.4, 0, 1, 1)";
+    readonly emphasized: "cubic-bezier(0.2, 0, 0, 1)";
+};
+/**
+ * Stagger timing for choreographed list entrances (quick replies, initial
+ * message batch). `step` is the per-item delay increment in milliseconds —
+ * a small cascade guides the eye and reads as a group (Gestalt common fate).
+ */
+export declare const MOTION_STAGGER: {
+    readonly step: 40;
+};
+export type MotionDurationKey = keyof typeof MOTION_DURATIONS;
+export type MotionEasingKey = keyof typeof MOTION_EASINGS;

package/dist/motion.js

@@ -0,0 +1,54 @@
+/**
+ * Canonical motion tokens for the Versiq widget — the single source of truth
+ * for animation durations, easing curves and stagger timing across BOTH widget
+ * bundles (the vanilla loader in `packages/widget` and the React embed in
+ * `apps/app/src/app/widget/embed`).
+ *
+ * **This module MUST stay free of any import** (no Zod, no sibling types). It is
+ * consumed by the loader through the dedicated subpath export
+ * `@gamaro.io/core-types/motion`, which guarantees the loader's UMD
+ * bundle never pulls in Zod via the barrel `index.ts`. Adding an import here
+ * would break that guarantee.
+ *
+ * Design rationale (see `docs/adr/ADR-018-widget-motion-design.md`):
+ * - Durations follow a harmonic scale; all UI transitions stay <= 400ms so the
+ *   interaction is perceived as instant (Doherty threshold, IBM 1982).
+ * - Easing curves are Material-3-style: entering elements decelerate (`enter`),
+ *   leaving elements accelerate (`exit`), in-place motion uses `standard`. The
+ *   "soft" feel comes from deceleration at the end of travel — never `linear`
+ *   nor a steep `ease-in-out` for UI transitions.
+ */
+/**
+ * Harmonic duration scale in milliseconds.
+ * - `instant` — no animation (reduced-motion fallback, snap states).
+ * - `fast` — micro-interactions (hover, focus).
+ * - `base` — standard transitions (fades, bubble entrances).
+ * - `slow` — panels, container resize, collapses.
+ * - `slower` — looping loaders (bounce/typing dots).
+ */
+export const MOTION_DURATIONS = {
+    instant: 0,
+    fast: 150,
+    base: 250,
+    slow: 400,
+    slower: 600,
+};
+/**
+ * Named easing curves. `standard` for in-place motion, `enter` for elements
+ * arriving (decelerate), `exit` for elements leaving (accelerate), `emphasized`
+ * for prominent panel transitions.
+ */
+export const MOTION_EASINGS = {
+    standard: "cubic-bezier(0.4, 0, 0.2, 1)",
+    enter: "cubic-bezier(0, 0, 0.2, 1)",
+    exit: "cubic-bezier(0.4, 0, 1, 1)",
+    emphasized: "cubic-bezier(0.2, 0, 0, 1)",
+};
+/**
+ * Stagger timing for choreographed list entrances (quick replies, initial
+ * message batch). `step` is the per-item delay increment in milliseconds —
+ * a small cascade guides the eye and reads as a group (Gestalt common fate).
+ */
+export const MOTION_STAGGER = {
+    step: 40,
+};

package/dist/postmessage.d.ts

@@ -0,0 +1,162 @@
+/**
+ * postMessage protocol between the widget iframe and its host page.
+ *
+ * Two directions share the `versiq:*` prefix:
+ *   - `WidgetCommand` — parent page → iframe (commands)
+ *   - `WidgetEvent`   — iframe → parent page (events)
+ *
+ * The `MESSAGE_TYPES` const aggregates every message type string across both
+ * directions. Consumers that treat the protocol opaquely (e.g. origin
+ * validation helpers) can rely on it to check `type.startsWith("versiq:")`
+ * without enumerating every member.
+ */
+import { z } from "zod";
+import { themeConfigSchema, type ThemeConfig } from "./theme";
+import { viewportModeSchema, type ViewportMode } from "./viewport";
+import { widgetConfigSchema, type WidgetConfig } from "./widget-config";
+export declare const messageRoleSchema: z.ZodEnum<{
+    user: "user";
+    assistant: "assistant";
+}>;
+export type MessageRole = z.infer<typeof messageRoleSchema>;
+export declare const widgetMessageSchema: z.ZodObject<{
+    role: z.ZodEnum<{
+        user: "user";
+        assistant: "assistant";
+    }>;
+    content: z.ZodString;
+}, z.core.$strip>;
+export type WidgetMessage = z.infer<typeof widgetMessageSchema>;
+/**
+ * Generic widget profile. The concrete shape depends on the vertical
+ * (`BuyerProfile` for real-estate, `B2BProfile` for b2b-qualification, etc.)
+ * — kept structural so verticals can evolve independently.
+ *
+ * As of #1993, no `WidgetEvent` member carries this type across the
+ * postMessage boundary anymore (see the signal-only `PROFILE_UPDATE`/
+ * `QUALIFIED` members below) — it is used for the widget's own internal
+ * conversation state and re-exported for integrators who want to type their
+ * own mirrored state.
+ */
+export type WidgetProfile = Record<string, unknown>;
+/**
+ * Exhaustive catalogue of every `versiq:*` message type used in either
+ * direction. Kept as a single const so a new event or command is declared in
+ * one place.
+ */
+export declare const MESSAGE_TYPES: {
+    readonly INIT: "versiq:init";
+    readonly OPEN: "versiq:open";
+    readonly CLOSE: "versiq:close";
+    readonly RESET: "versiq:reset";
+    readonly SET_THEME: "versiq:setTheme";
+    readonly VIEWPORT: "versiq:viewport";
+    readonly IDENTIFY: "versiq:identify";
+    readonly READY: "versiq:ready";
+    readonly PROFILE_UPDATE: "versiq:profile-update";
+    readonly MESSAGE: "versiq:message";
+    readonly QUALIFIED: "versiq:qualified";
+    readonly ERROR: "versiq:error";
+    readonly QUOTA_WARNING: "versiq:quota-warning";
+    readonly QUOTA_EXCEEDED: "versiq:quota-exceeded";
+    readonly FUNNEL_STAGE_CHANGE: "versiq:funnel-stage-change";
+    readonly CTA_SHOWN: "versiq:cta-shown";
+    readonly CTA_CLICKED: "versiq:cta-clicked";
+    readonly LEAD_CAPTURED: "versiq:lead-captured";
+    readonly IDENTITY_VERIFIED: "versiq:identity-verified";
+};
+export type MessageType = (typeof MESSAGE_TYPES)[keyof typeof MESSAGE_TYPES];
+export type WidgetCommand = {
+    type: typeof MESSAGE_TYPES.INIT;
+    config: WidgetConfig;
+} | {
+    type: typeof MESSAGE_TYPES.OPEN;
+} | {
+    type: typeof MESSAGE_TYPES.CLOSE;
+} | {
+    type: typeof MESSAGE_TYPES.RESET;
+} | {
+    type: typeof MESSAGE_TYPES.SET_THEME;
+    theme: ThemeConfig;
+} | {
+    type: typeof MESSAGE_TYPES.VIEWPORT;
+    mode: ViewportMode;
+} | {
+    type: typeof MESSAGE_TYPES.IDENTIFY;
+    email: string;
+    userId?: string;
+    userHash: string;
+};
+export type WidgetEvent = {
+    type: typeof MESSAGE_TYPES.READY;
+} | {
+    type: typeof MESSAGE_TYPES.PROFILE_UPDATE;
+} | {
+    type: typeof MESSAGE_TYPES.MESSAGE;
+    message: WidgetMessage;
+} | {
+    type: typeof MESSAGE_TYPES.QUALIFIED;
+} | {
+    type: typeof MESSAGE_TYPES.ERROR;
+    code: string;
+    message: string;
+} | {
+    type: typeof MESSAGE_TYPES.OPEN;
+} | {
+    type: typeof MESSAGE_TYPES.CLOSE;
+} | {
+    type: typeof MESSAGE_TYPES.QUOTA_WARNING;
+    remaining: number;
+    limit: number;
+} | {
+    type: typeof MESSAGE_TYPES.QUOTA_EXCEEDED;
+} | {
+    type: typeof MESSAGE_TYPES.FUNNEL_STAGE_CHANGE;
+    stage: string;
+    previousStage: string | null;
+} | {
+    type: typeof MESSAGE_TYPES.CTA_SHOWN;
+    ctaType: string;
+    objectiveId?: string;
+} | {
+    type: typeof MESSAGE_TYPES.CTA_CLICKED;
+    ctaType: string;
+    objectiveId?: string;
+} | {
+    type: typeof MESSAGE_TYPES.LEAD_CAPTURED;
+    hasEmail: boolean;
+    hasPhone: boolean;
+} | {
+    type: typeof MESSAGE_TYPES.IDENTITY_VERIFIED;
+    email: string;
+    userId?: string;
+};
+/**
+ * Short keys (no `versiq:` prefix) used by the widget public API (on/off).
+ */
+export type WidgetEventType = "ready" | "profile-update" | "message" | "qualified" | "error" | "open" | "close" | "quota-warning" | "quota-exceeded" | "funnel-stage-change" | "cta-shown" | "cta-clicked" | "lead-captured" | "identity-verified" | "widget-unavailable";
+/**
+ * Payload emitted with the `widget-unavailable` SDK event (#867).
+ *
+ * Fired by the SDK (parent side) when the iframe loader exhausted all
+ * retries — distinct from the iframe-emitted `versiq:error` which signals
+ * a runtime failure of an already-loaded widget.
+ *
+ * Dual-emission contract: when the loader fails, the SDK emits BOTH
+ *   1. `widget-unavailable` (this payload) — the canonical SDK-side event
+ *   2. `error` with `code: "IFRAME_UNAVAILABLE"` — preserved so hosts that
+ *      subscribed to `error` before #867 still observe the failure
+ *      without having to migrate. New integrations SHOULD prefer
+ *      `widget-unavailable` for SDK-load failures and reserve `error`
+ *      for runtime errors surfaced by the loaded widget.
+ */
+export declare const widgetUnavailablePayloadSchema: z.ZodObject<{
+    reason: z.ZodEnum<{
+        error: "error";
+        timeout: "timeout";
+    }>;
+    attempts: z.ZodNumber;
+}, z.core.$strip>;
+export type WidgetUnavailablePayload = z.infer<typeof widgetUnavailablePayloadSchema>;
+export type WidgetEventHandler<T = unknown> = (data: T) => void;
+export { themeConfigSchema, viewportModeSchema, widgetConfigSchema };

package/dist/postmessage.js

@@ -0,0 +1,91 @@
+/**
+ * postMessage protocol between the widget iframe and its host page.
+ *
+ * Two directions share the `versiq:*` prefix:
+ *   - `WidgetCommand` — parent page → iframe (commands)
+ *   - `WidgetEvent`   — iframe → parent page (events)
+ *
+ * The `MESSAGE_TYPES` const aggregates every message type string across both
+ * directions. Consumers that treat the protocol opaquely (e.g. origin
+ * validation helpers) can rely on it to check `type.startsWith("versiq:")`
+ * without enumerating every member.
+ */
+import { z } from "zod";
+import { themeConfigSchema } from "./theme";
+import { viewportModeSchema } from "./viewport";
+import { widgetConfigSchema } from "./widget-config";
+// ============================================================================
+// Message primitives
+// ============================================================================
+export const messageRoleSchema = z
+    .enum(["user", "assistant"])
+    .describe("Message sender role");
+export const widgetMessageSchema = z.object({
+    role: messageRoleSchema.describe("Message sender role"),
+    content: z
+        .string()
+        .max(10000)
+        .describe("Message content (max 10000 characters)"),
+});
+// ============================================================================
+// Message type catalogue
+// ============================================================================
+/**
+ * Exhaustive catalogue of every `versiq:*` message type used in either
+ * direction. Kept as a single const so a new event or command is declared in
+ * one place.
+ */
+export const MESSAGE_TYPES = {
+    // Parent → iframe (commands)
+    INIT: "versiq:init",
+    OPEN: "versiq:open",
+    CLOSE: "versiq:close",
+    RESET: "versiq:reset",
+    SET_THEME: "versiq:setTheme",
+    VIEWPORT: "versiq:viewport",
+    IDENTIFY: "versiq:identify",
+    // iframe → parent (events)
+    READY: "versiq:ready",
+    PROFILE_UPDATE: "versiq:profile-update",
+    MESSAGE: "versiq:message",
+    QUALIFIED: "versiq:qualified",
+    ERROR: "versiq:error",
+    QUOTA_WARNING: "versiq:quota-warning",
+    QUOTA_EXCEEDED: "versiq:quota-exceeded",
+    FUNNEL_STAGE_CHANGE: "versiq:funnel-stage-change",
+    CTA_SHOWN: "versiq:cta-shown",
+    CTA_CLICKED: "versiq:cta-clicked",
+    LEAD_CAPTURED: "versiq:lead-captured",
+    IDENTITY_VERIFIED: "versiq:identity-verified",
+};
+/**
+ * Payload emitted with the `widget-unavailable` SDK event (#867).
+ *
+ * Fired by the SDK (parent side) when the iframe loader exhausted all
+ * retries — distinct from the iframe-emitted `versiq:error` which signals
+ * a runtime failure of an already-loaded widget.
+ *
+ * Dual-emission contract: when the loader fails, the SDK emits BOTH
+ *   1. `widget-unavailable` (this payload) — the canonical SDK-side event
+ *   2. `error` with `code: "IFRAME_UNAVAILABLE"` — preserved so hosts that
+ *      subscribed to `error` before #867 still observe the failure
+ *      without having to migrate. New integrations SHOULD prefer
+ *      `widget-unavailable` for SDK-load failures and reserve `error`
+ *      for runtime errors surfaced by the loaded widget.
+ */
+export const widgetUnavailablePayloadSchema = z
+    .object({
+    reason: z
+        .enum(["timeout", "error"])
+        .describe("Why the iframe load failed (timeout vs. transport error)"),
+    attempts: z
+        .number()
+        .int()
+        .min(1)
+        .describe("Total attempts made before giving up (e.g. 3 = 1 + 2 retries)"),
+})
+    .describe("Payload emitted with the widget-unavailable SDK event (#867)");
+// Re-export schemas that participate in the protocol for consumers that want
+// runtime validation (e.g. widget bootstrap parsing a `WidgetConfig`).
+export { themeConfigSchema, viewportModeSchema, widgetConfigSchema };
+// `widgetUnavailablePayloadSchema` is declared above with its derived type.

package/dist/session.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Session cookie naming + session-id validation — the single source of truth
+ * shared by the app server (`apps/app/src/lib/security/session-cookie.ts`) and
+ * the E2E browser suite (`tests/e2e-browser`). Extracted here (#918 review) to
+ * remove the two previously-duplicated copies that could silently desync: a
+ * drift in the cookie prefix or the sanitization regex would otherwise break
+ * sessionId capture only in the browser run, a failure hard to attribute.
+ *
+ * **This module MUST stay import-free (pure)**, like `./motion` — it is exposed
+ * via the dedicated subpath `@gamaro.io/core-types/session` so a consumer
+ * (e.g. the test workspace, the vanilla loader) can pull just these helpers
+ * without dragging Zod in via the barrel `index.ts`.
+ */
+/**
+ * Per-vertical session cookie name. Each vertical owns its own cookie to prevent
+ * profile-schema conflicts. Any character outside `[a-z0-9-]` (case-insensitive)
+ * is sanitized to `_` (each char maps to one `_`, no collapsing), so
+ * `real-estate` stays `versiq_session_real-estate`.
+ */
+export declare function getSessionCookieName(verticalId: string): string;
+/**
+ * Validate the UUID shape of a session id. The length pre-check is
+ * defense-in-depth (avoids running the regex on arbitrarily long strings).
+ */
+export declare function isValidSessionId(value: string): boolean;

package/dist/session.js

@@ -0,0 +1,32 @@
+/**
+ * Session cookie naming + session-id validation — the single source of truth
+ * shared by the app server (`apps/app/src/lib/security/session-cookie.ts`) and
+ * the E2E browser suite (`tests/e2e-browser`). Extracted here (#918 review) to
+ * remove the two previously-duplicated copies that could silently desync: a
+ * drift in the cookie prefix or the sanitization regex would otherwise break
+ * sessionId capture only in the browser run, a failure hard to attribute.
+ *
+ * **This module MUST stay import-free (pure)**, like `./motion` — it is exposed
+ * via the dedicated subpath `@gamaro.io/core-types/session` so a consumer
+ * (e.g. the test workspace, the vanilla loader) can pull just these helpers
+ * without dragging Zod in via the barrel `index.ts`.
+ */
+/**
+ * Per-vertical session cookie name. Each vertical owns its own cookie to prevent
+ * profile-schema conflicts. Any character outside `[a-z0-9-]` (case-insensitive)
+ * is sanitized to `_` (each char maps to one `_`, no collapsing), so
+ * `real-estate` stays `versiq_session_real-estate`.
+ */
+export function getSessionCookieName(verticalId) {
+    const sanitized = verticalId.replace(/[^a-z0-9-]/gi, "_");
+    return `versiq_session_${sanitized}`;
+}
+/**
+ * Validate the UUID shape of a session id. The length pre-check is
+ * defense-in-depth (avoids running the regex on arbitrarily long strings).
+ */
+export function isValidSessionId(value) {
+    if (value.length !== 36)
+        return false;
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
+}

package/dist/theme-resolver.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Theme resolver — single source of truth for `ThemeConfig` → CSS-ready values.
+ *
+ * Pure function consumed by:
+ *  - `apps/app/src/app/widget/embed/EmbedChat.tsx` (iframe runtime)
+ *  - `apps/app/src/components/portal/sandbox/WidgetMockPreview.tsx` (admin preview)
+ *
+ * Before this module existed, the same resolution rules were duplicated across
+ * the two call sites (cf. audit `tmp/widget-customization-review.md` § 3.4 —
+ * fuite n° 3 of the verdict "abstraction qui ne tient pas sa promesse"). Any
+ * evolution had to be mirrored by hand, with no compiler check. The function
+ * here is the contract; both callers MUST consume it.
+ *
+ * Dark-mode policy:
+ *   `backgroundColor` and `textColor` admin-side hex overrides apply in
+ *   LIGHT MODE ONLY. The widget's `colorScheme: "dark"` token flips surface
+ *   tokens via the `.dark` CSS class on the iframe root — forcing a saved
+ *   "#FFFFFF" through dark mode would defeat the toggle and yield a
+ *   white-on-white outcome on the visitor's site. When `isDark` is true,
+ *   those two fields fall back to the resolver's `defaults` (typically CSS
+ *   variables that respond to `.dark`).
+ *
+ *   `primaryColor` is brand-side and applies in both schemes: the assistant
+ *   bubble and the launcher button must stay the brand colour even on a
+ *   dark surface.
+ */
+import type { ThemeConfig } from "./theme";
+/**
+ * Caller-supplied fallback palette. Each consumer (runtime, preview) passes
+ * the same constant — that is what guarantees alignment by construction. The
+ * test contract (`theme-resolver.test.ts`) asserts identical output for
+ * identical input across callers.
+ */
+export interface ThemeDefaults {
+    /** Brand colour applied to launcher + user bubble. Used in BOTH schemes. */
+    primaryColor: string;
+    /** Background applied to the widget surface. Used only when `isDark === false`. */
+    backgroundColor: string;
+    /** Foreground text colour. Used only when `isDark === false`. */
+    textColor: string;
+    /** Default radius (in pixels) used when `theme.borderRadius == null`. */
+    borderRadiusPx: number;
+    /** Default font stack used when `theme.fontFamily == null`. */
+    fontFamily: string;
+}
+export interface ResolvedTheme {
+    primaryColor: string;
+    backgroundColor: string;
+    textColor: string;
+    /** CSS string ready to apply (e.g. `"16px"`). */
+    borderRadius: string;
+    fontFamily: string;
+}
+export declare function resolveTheme(theme: ThemeConfig | null | undefined, isDark: boolean, defaults: ThemeDefaults): ResolvedTheme;

package/dist/theme-resolver.js

@@ -0,0 +1,40 @@
+/**
+ * Theme resolver — single source of truth for `ThemeConfig` → CSS-ready values.
+ *
+ * Pure function consumed by:
+ *  - `apps/app/src/app/widget/embed/EmbedChat.tsx` (iframe runtime)
+ *  - `apps/app/src/components/portal/sandbox/WidgetMockPreview.tsx` (admin preview)
+ *
+ * Before this module existed, the same resolution rules were duplicated across
+ * the two call sites (cf. audit `tmp/widget-customization-review.md` § 3.4 —
+ * fuite n° 3 of the verdict "abstraction qui ne tient pas sa promesse"). Any
+ * evolution had to be mirrored by hand, with no compiler check. The function
+ * here is the contract; both callers MUST consume it.
+ *
+ * Dark-mode policy:
+ *   `backgroundColor` and `textColor` admin-side hex overrides apply in
+ *   LIGHT MODE ONLY. The widget's `colorScheme: "dark"` token flips surface
+ *   tokens via the `.dark` CSS class on the iframe root — forcing a saved
+ *   "#FFFFFF" through dark mode would defeat the toggle and yield a
+ *   white-on-white outcome on the visitor's site. When `isDark` is true,
+ *   those two fields fall back to the resolver's `defaults` (typically CSS
+ *   variables that respond to `.dark`).
+ *
+ *   `primaryColor` is brand-side and applies in both schemes: the assistant
+ *   bubble and the launcher button must stay the brand colour even on a
+ *   dark surface.
+ */
+export function resolveTheme(theme, isDark, defaults) {
+    const primaryColor = theme?.primaryColor ?? defaults.primaryColor;
+    const backgroundColor = isDark
+        ? defaults.backgroundColor
+        : (theme?.backgroundColor ?? defaults.backgroundColor);
+    const textColor = isDark
+        ? defaults.textColor
+        : (theme?.textColor ?? defaults.textColor);
+    const borderRadius = theme?.borderRadius != null
+        ? `${theme.borderRadius}px`
+        : `${defaults.borderRadiusPx}px`;
+    const fontFamily = theme?.fontFamily ?? defaults.fontFamily;
+    return { primaryColor, backgroundColor, textColor, borderRadius, fontFamily };
+}

package/dist/theme.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Theme configuration schema for customizing widget appearance.
+ *
+ * Cross-boundary contract shared by the widget SDK (`@gamaro.io/widget`) and the
+ * app host (`apps/app`). Both workspaces historically redefined the same
+ * fields — this module is the single source of truth.
+ */
+import { z } from "zod";
+export declare const themeConfigSchema: z.ZodObject<{
+    primaryColor: z.ZodOptional<z.ZodString>;
+    backgroundColor: z.ZodOptional<z.ZodString>;
+    textColor: z.ZodOptional<z.ZodString>;
+    borderRadius: z.ZodOptional<z.ZodNumber>;
+    fontFamily: z.ZodOptional<z.ZodString>;
+    colorScheme: z.ZodOptional<z.ZodEnum<{
+        light: "light";
+        dark: "dark";
+        auto: "auto";
+    }>>;
+}, z.core.$strip>;
+export type ThemeConfig = z.infer<typeof themeConfigSchema>;
+export type ColorScheme = NonNullable<ThemeConfig["colorScheme"]>;

package/dist/theme.js

@@ -0,0 +1,39 @@
+/**
+ * Theme configuration schema for customizing widget appearance.
+ *
+ * Cross-boundary contract shared by the widget SDK (`@gamaro.io/widget`) and the
+ * app host (`apps/app`). Both workspaces historically redefined the same
+ * fields — this module is the single source of truth.
+ */
+import { z } from "zod";
+// 6-digit hex color (e.g. "#3B82F6"). Lower or upper case accepted.
+// `max(20)` is kept on top of the regex as a belt-and-braces guard against
+// pre-validation length attacks even if the regex were ever loosened.
+const HEX_COLOR_REGEX = /^#[0-9a-fA-F]{6}$/;
+const HEX_COLOR_MESSAGE = "Color must be a 6-digit hex code (e.g. '#3B82F6'). Short hex, rgb(), and named colors are not supported.";
+export const themeConfigSchema = z.object({
+    primaryColor: z
+        .string()
+        .max(20)
+        .regex(HEX_COLOR_REGEX, HEX_COLOR_MESSAGE)
+        .describe("Primary brand color (hex format, e.g., '#3B82F6')")
+        .optional(),
+    backgroundColor: z
+        .string()
+        .max(20)
+        .regex(HEX_COLOR_REGEX, HEX_COLOR_MESSAGE)
+        .describe("Background color for the widget container")
+        .optional(),
+    textColor: z
+        .string()
+        .max(20)
+        .regex(HEX_COLOR_REGEX, HEX_COLOR_MESSAGE)
+        .describe("Text color")
+        .optional(),
+    borderRadius: z.number().describe("Border radius in pixels").optional(),
+    fontFamily: z.string().max(100).describe("Font family").optional(),
+    colorScheme: z
+        .enum(["light", "dark", "auto"])
+        .describe("Widget color scheme: 'light' (default), 'dark', or 'auto' (follows the visitor's prefers-color-scheme).")
+        .optional(),
+});

package/dist/viewport.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Viewport, breakpoints, responsive and position contracts for the widget.
+ *
+ * Cross-boundary contract shared by `@gamaro.io/widget` (runtime enforcement) and
+ * `apps/app` (sandbox preview, embed layout).
+ */
+import { z } from "zod";
+export declare const viewportModeSchema: z.ZodEnum<{
+    mobile: "mobile";
+    tablet: "tablet";
+    desktop: "desktop";
+}>;
+export type ViewportMode = z.infer<typeof viewportModeSchema>;
+export declare const widgetPositionSchema: z.ZodEnum<{
+    "bottom-right": "bottom-right";
+    "bottom-left": "bottom-left";
+    inline: "inline";
+}>;
+export type WidgetPosition = z.infer<typeof widgetPositionSchema>;
+export declare const breakpointsConfigSchema: z.ZodObject<{
+    mobile: z.ZodOptional<z.ZodNumber>;
+    tablet: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type BreakpointsConfig = z.infer<typeof breakpointsConfigSchema>;
+export declare const responsiveConfigSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    breakpoints: z.ZodOptional<z.ZodObject<{
+        mobile: z.ZodOptional<z.ZodNumber>;
+        tablet: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ResponsiveConfig = z.infer<typeof responsiveConfigSchema>;

package/dist/viewport.js

@@ -0,0 +1,36 @@
+/**
+ * Viewport, breakpoints, responsive and position contracts for the widget.
+ *
+ * Cross-boundary contract shared by `@gamaro.io/widget` (runtime enforcement) and
+ * `apps/app` (sandbox preview, embed layout).
+ */
+import { z } from "zod";
+export const viewportModeSchema = z
+    .enum(["mobile", "tablet", "desktop"])
+    .describe("Viewport mode: mobile (<480px), tablet (480-768px), desktop (>768px)");
+export const widgetPositionSchema = z
+    .enum(["bottom-right", "bottom-left", "inline"])
+    .describe("Widget position on the page");
+export const breakpointsConfigSchema = z.object({
+    mobile: z
+        .number()
+        .min(0)
+        .max(1000)
+        .describe("Max width for mobile viewport (default: 480)")
+        .optional(),
+    tablet: z
+        .number()
+        .min(0)
+        .max(2000)
+        .describe("Max width for tablet viewport (default: 768)")
+        .optional(),
+});
+export const responsiveConfigSchema = z.object({
+    enabled: z
+        .boolean()
+        .describe("Enable responsive behavior (default: true)")
+        .optional(),
+    breakpoints: breakpointsConfigSchema
+        .describe("Custom breakpoint values")
+        .optional(),
+});

package/dist/widget-config.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Full widget configuration contract.
+ *
+ * Consumed by `@gamaro.io/widget` (config parsing and iframe bootstrap) and by
+ * `apps/app` sandbox/preview components via `@gamaro.io/widget`'s re-export.
+ */
+import { z } from "zod";
+export declare const widgetConfigSchema: z.ZodObject<{
+    theme: z.ZodOptional<z.ZodObject<{
+        primaryColor: z.ZodOptional<z.ZodString>;
+        backgroundColor: z.ZodOptional<z.ZodString>;
+        textColor: z.ZodOptional<z.ZodString>;
+        borderRadius: z.ZodOptional<z.ZodNumber>;
+        fontFamily: z.ZodOptional<z.ZodString>;
+        colorScheme: z.ZodOptional<z.ZodEnum<{
+            light: "light";
+            dark: "dark";
+            auto: "auto";
+        }>>;
+    }, z.core.$strip>>;
+    position: z.ZodOptional<z.ZodEnum<{
+        "bottom-right": "bottom-right";
+        "bottom-left": "bottom-left";
+        inline: "inline";
+    }>>;
+    open: z.ZodOptional<z.ZodBoolean>;
+    container: z.ZodOptional<z.ZodUnion<readonly [z.ZodCustom<HTMLElement, HTMLElement>, z.ZodString]>>;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    debug: z.ZodOptional<z.ZodBoolean>;
+    responsive: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        breakpoints: z.ZodOptional<z.ZodObject<{
+            mobile: z.ZodOptional<z.ZodNumber>;
+            tablet: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    showProfile: z.ZodOptional<z.ZodBoolean>;
+    language: z.ZodOptional<z.ZodString>;
+    apiKey: z.ZodString;
+    email: z.ZodOptional<z.ZodString>;
+    userId: z.ZodOptional<z.ZodString>;
+    userHash: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WidgetConfig = z.infer<typeof widgetConfigSchema>;

package/dist/widget-config.js

@@ -0,0 +1,62 @@
+/**
+ * Full widget configuration contract.
+ *
+ * Consumed by `@gamaro.io/widget` (config parsing and iframe bootstrap) and by
+ * `apps/app` sandbox/preview components via `@gamaro.io/widget`'s re-export.
+ */
+import { z } from "zod";
+import { themeConfigSchema } from "./theme";
+import { responsiveConfigSchema, widgetPositionSchema } from "./viewport";
+export const widgetConfigSchema = z.object({
+    theme: themeConfigSchema.describe("Custom theme configuration").optional(),
+    position: widgetPositionSchema
+        .describe("Widget position (default: 'bottom-right')")
+        .optional(),
+    open: z.boolean().describe("Initial open state (default: false)").optional(),
+    container: z
+        .union([
+        z.custom((val) => val instanceof HTMLElement),
+        z.string().max(200),
+    ])
+        .describe("Container element for inline mode")
+        .optional(),
+    baseUrl: z
+        .string()
+        .url()
+        .max(200)
+        .describe("Base URL for the widget embed (default: production URL)")
+        .optional(),
+    debug: z.boolean().describe("Enable debug logging").optional(),
+    responsive: responsiveConfigSchema
+        .describe("Responsive behavior configuration")
+        .optional(),
+    showProfile: z
+        .boolean()
+        .describe("Show profile panel in widget header (default: false)")
+        .optional(),
+    language: z
+        .string()
+        .max(10)
+        .describe("Language for UI labels (e.g., 'fr', 'en'). Defaults to browser language.")
+        .optional(),
+    apiKey: z
+        .string()
+        .max(100)
+        .describe("Publishable API key (pk_*) for application authentication"),
+    email: z
+        .string()
+        .email()
+        .max(255)
+        .describe("Pre-identified user email (host-attested identity)")
+        .optional(),
+    userId: z
+        .string()
+        .max(255)
+        .describe("Host-side unique user identifier")
+        .optional(),
+    userHash: z
+        .string()
+        .max(128)
+        .describe("HMAC-SHA256 of email (or userId), signed with identity secret")
+        .optional(),
+});

package/dist/widget-runtime-config.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Widget runtime config — server-authoritative, admin-editable.
+ *
+ * This schema defines what the admin portal can edit for a given Application
+ * and what the widget SDK receives at bootstrap via `GET /api/application/config`.
+ * It is deliberately disjoint from `widgetConfigSchema` (which contains the
+ * host-context attributes `apiKey`/`container`/`baseUrl`/`debug`/identity
+ * fields that can only live on the integrator's page).
+ *
+ * Single source of truth consumed by:
+ *  - `apps/app` admin route handlers (Zod second-gate on response + PUT body)
+ *  - `apps/app` portal widget editor (form schema)
+ *  - `packages/widget` config resolver (server-wins merge policy)
+ *
+ * Storage: `applications.widget_config` JSONB column. Cache-invalidated on
+ * update via `invalidateKeyCacheForApplication`.
+ *
+ * Part of #726 — unifying widget config so the integration reduces to
+ * `<script data-api-key="pk_live_…"></script>`.
+ */
+import { z } from "zod";
+export declare const widgetRuntimeConfigSchema: z.ZodObject<{
+    theme: z.ZodOptional<z.ZodObject<{
+        primaryColor: z.ZodOptional<z.ZodString>;
+        backgroundColor: z.ZodOptional<z.ZodString>;
+        textColor: z.ZodOptional<z.ZodString>;
+        borderRadius: z.ZodOptional<z.ZodNumber>;
+        fontFamily: z.ZodOptional<z.ZodString>;
+        colorScheme: z.ZodOptional<z.ZodEnum<{
+            light: "light";
+            dark: "dark";
+            auto: "auto";
+        }>>;
+    }, z.core.$strip>>;
+    position: z.ZodOptional<z.ZodEnum<{
+        "bottom-right": "bottom-right";
+        "bottom-left": "bottom-left";
+        inline: "inline";
+    }>>;
+    language: z.ZodOptional<z.ZodString>;
+    showProfile: z.ZodOptional<z.ZodBoolean>;
+    open: z.ZodOptional<z.ZodBoolean>;
+    brand: z.ZodOptional<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        avatarUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type WidgetRuntimeConfig = z.infer<typeof widgetRuntimeConfigSchema>;

package/dist/widget-runtime-config.js

@@ -0,0 +1,63 @@
+/**
+ * Widget runtime config — server-authoritative, admin-editable.
+ *
+ * This schema defines what the admin portal can edit for a given Application
+ * and what the widget SDK receives at bootstrap via `GET /api/application/config`.
+ * It is deliberately disjoint from `widgetConfigSchema` (which contains the
+ * host-context attributes `apiKey`/`container`/`baseUrl`/`debug`/identity
+ * fields that can only live on the integrator's page).
+ *
+ * Single source of truth consumed by:
+ *  - `apps/app` admin route handlers (Zod second-gate on response + PUT body)
+ *  - `apps/app` portal widget editor (form schema)
+ *  - `packages/widget` config resolver (server-wins merge policy)
+ *
+ * Storage: `applications.widget_config` JSONB column. Cache-invalidated on
+ * update via `invalidateKeyCacheForApplication`.
+ *
+ * Part of #726 — unifying widget config so the integration reduces to
+ * `<script data-api-key="pk_live_…"></script>`.
+ */
+import { z } from "zod";
+import { themeConfigSchema } from "./theme";
+import { widgetPositionSchema } from "./viewport";
+export const widgetRuntimeConfigSchema = z
+    .object({
+    theme: themeConfigSchema
+        .describe("Full visual theme palette applied by the widget. Admin-configured, no client-side override.")
+        .optional(),
+    position: widgetPositionSchema
+        .describe("Default launcher position. `inline` only applies when integrator supplies `data-container`.")
+        .optional(),
+    language: z
+        .string()
+        .max(10)
+        .describe("Locale forced for widget UI labels (ISO 639-1). Falls back to browser language when null.")
+        .optional(),
+    showProfile: z
+        .boolean()
+        .describe("Whether the widget header exposes the profile panel to end-users.")
+        .optional(),
+    open: z
+        .boolean()
+        .describe("Default open state on load. Host can still call `window.Versiq.open()` programmatically.")
+        .optional(),
+    brand: z
+        .object({
+        title: z
+            .string()
+            .max(60)
+            .describe("Custom widget header title. Falls back to a vertical-specific default (e.g. 'Versiq Chat' for B2B) when unset.")
+            .optional(),
+        avatarUrl: z
+            .string()
+            .url()
+            .max(2048)
+            .describe("Public URL of the custom widget avatar (PNG or JPEG). MUST originate from the branding-upload endpoint — arbitrary external URLs are rejected at the API boundary.")
+            .optional(),
+    })
+        .strict()
+        .describe("White-label branding overrides (issue #1083 Piste 5). Both fields are optional.")
+        .optional(),
+})
+    .strict();

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@gamaro.io/core-types",
+  "version": "0.6.0",
+  "description": "Cross-workspace TypeScript contracts and Zod schemas consumed by @gamaro.io/widget. Intended as a peer of the widget SDK.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./motion": {
+      "types": "./dist/motion.d.ts",
+      "import": "./dist/motion.js",
+      "default": "./dist/motion.js"
+    },
+    "./session": {
+      "types": "./dist/session.d.ts",
+      "import": "./dist/session.js",
+      "default": "./dist/session.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Sébastien Dolard <admin@gamaro.io>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sdolard/Toize.git",
+    "directory": "packages/core-types"
+  },
+  "homepage": "https://github.com/sdolard/Toize/tree/main/packages/core-types#readme",
+  "bugs": {
+    "url": "https://github.com/sdolard/Toize/issues"
+  },
+  "keywords": [
+    "gamaro",
+    "widget",
+    "types",
+    "zod",
+    "schemas",
+    "sdk"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@microsoft/api-extractor": "^7.58.12",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "pnpm clean && tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "typecheck": "tsc --noEmit",
+    "typecheck:ci": "pnpm typecheck",
+    "api-extractor:check": "api-extractor run --verbose -c api-extractor.json && api-extractor run --verbose -c api-extractor.motion.json && api-extractor run --verbose -c api-extractor.session.json",
+    "api-extractor:local": "api-extractor run --local --verbose -c api-extractor.json && api-extractor run --local --verbose -c api-extractor.motion.json && api-extractor run --local --verbose -c api-extractor.session.json"
+  }
+}