@syntrologie/runtime-sdk 0.2.21 → 1.0.0-canary.1

package/dist/token.js

@@ -5,7 +5,7 @@
  * It bundles all necessary credentials (experiments, telemetry, config) into
  * a single string that clients can use to initialize the SDK.
  */
-const TOKEN_PREFIX = "syn_";
+const TOKEN_PREFIX = 'syn_';
 /**
  * Decode a Syntro token into its payload.
  *
@@ -19,7 +19,7 @@ export function decodeToken(token) {
     }
     const base64 = token.slice(TOKEN_PREFIX.length);
     // Convert base64url to standard base64
-    const standardBase64 = base64.replace(/-/g, "+").replace(/_/g, "/");
+    const standardBase64 = base64.replace(/-/g, '+').replace(/_/g, '/');
     const json = atob(standardBase64);
     const payload = JSON.parse(json);
     if (payload.v !== 1) {
@@ -38,10 +38,7 @@ export function decodeToken(token) {
 export function encodeToken(payload) {
     const json = JSON.stringify(payload);
     // Convert to base64url (URL-safe, no padding)
-    const base64 = btoa(json)
-        .replace(/\+/g, "-")
-        .replace(/\//g, "_")
-        .replace(/=+$/, "");
+    const base64 = btoa(json).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
     return TOKEN_PREFIX + base64;
 }
 //# sourceMappingURL=token.js.map

package/dist/token.js.map

@@ -1 +1 @@
-{"version":3,"file":"token.js","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,YAAY,GAAG,MAAM,CAAC;AAyB5B;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAClE,CAAC;IAED,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;IAChD,uCAAuC;IACvC,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACpE,MAAM,IAAI,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC;IAClC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAuB,CAAC;IAEvD,IAAI,OAAO,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,8BAA8B,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,OAA2B;IACrD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACrC,8CAA8C;IAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC;SACtB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACtB,OAAO,YAAY,GAAG,MAAM,CAAC;AAC/B,CAAC"}
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,YAAY,GAAG,MAAM,CAAC;AA4B5B;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAClE,CAAC;IAED,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;IAChD,uCAAuC;IACvC,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACpE,MAAM,IAAI,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC;IAClC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAuB,CAAC;IAEvD,IAAI,OAAO,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,8BAA8B,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,OAA2B;IACrD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACrC,8CAA8C;IAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACrF,OAAO,YAAY,GAAG,MAAM,CAAC;AAC/B,CAAC"}

package/dist/types-only.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Types-only export for app packages.
+ *
+ * This file re-exports action types without importing any runtime code,
+ * allowing app packages to import types without circular dependency issues.
+ *
+ * Apps should import from "@syntrologie/runtime-sdk/types" instead of
+ * the main entry point when they only need type definitions.
+ */
+/**
+ * Props passed to editor panel components.
+ */
+export interface EditorPanelProps {
+    /** The current config for this app's portion */
+    config: Record<string, unknown>;
+    /** Callback when config changes */
+    onChange: (config: Record<string, unknown>) => void;
+    /** Editor utilities */
+    editor: {
+        /** Mark the editor as dirty (has unsaved changes) */
+        setDirty: (dirty: boolean) => void;
+        /** Navigate back to home */
+        navigateHome: () => Promise<boolean>;
+        /** Save the current config */
+        save: () => Promise<void>;
+        /** Publish the current config */
+        publish: (captureScreenshot?: boolean) => Promise<void>;
+    };
+    /** Platform client for API calls (optional) */
+    platformClient?: unknown;
+}
+export type { StaticSurfaceSlot, InlineSurfaceSlot, AdjacentSurfaceSlot, SurfaceSlot, HighlightStyle, BadgePosition, TooltipContent, TooltipTrigger, InsertPosition, WidgetConfig, HighlightAction, PulseAction, BadgeAction, TooltipAction, InsertHtmlAction, SetTextAction, SetAttrAction, AddClassAction, RemoveClassAction, SetStyleAction, MountWidgetAction, ScrollToAction, NavigateAction, ActionStep, ActionKind, ActionState, ActionHandle, BatchActionHandle, ActiveAction, ValidationError, ValidationWarning, ValidationResult, ExecutorCleanup, ExecutorUpdate, ExecutorResult, ActionExecutor, ExecutorContext, } from './actions/types';

package/dist/types-only.js

@@ -0,0 +1,11 @@
+/**
+ * Types-only export for app packages.
+ *
+ * This file re-exports action types without importing any runtime code,
+ * allowing app packages to import types without circular dependency issues.
+ *
+ * Apps should import from "@syntrologie/runtime-sdk/types" instead of
+ * the main entry point when they only need type definitions.
+ */
+export {};
+//# sourceMappingURL=types-only.js.map

package/dist/types-only.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-only.js","sourceRoot":"","sources":["../src/types-only.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/types.d.ts

@@ -1,11 +1,25 @@
+export { SDK_VERSION } from './version';
+/**
+ * SDK schema version in Major.Minor format (e.g., "2.0", "2.1").
+ * Used for compatibility checking between SDK and backend configs.
+ * Sent in X-SDK-Schema-Version header.
+ *
+ * Bump rules:
+ * - Major: Breaking changes (field removal, type changes)
+ * - Minor: Backwards-compatible additions (new optional fields)
+ *
+ * @since 2.0.0
+ */
+export declare const SDK_SCHEMA_VERSION = "2.0";
+export type { ActionStep } from './actions/types';
 /**
  * Props passed to every tile component when mounted
  */
 export interface TileComponentProps {
     config: TileConfig;
     isExpanded: boolean;
-    surface: "overlay" | "wheel";
-    telemetry?: import("./telemetry/types").TelemetryClient;
+    surface: 'overlay' | 'wheel';
+    telemetry?: import('./telemetry/types').TelemetryClient;
 }
 /**
  * Interface for registering custom tile components
@@ -16,15 +30,15 @@ export interface TileComponent {
 /**
  * All available block types organized by category
  */
-export type NotificationBlockType = "alert" | "success" | "warning" | "info" | "error";
-export type MediaBlockType = "video" | "gallery" | "code";
-export type InteractiveBlockType = "form" | "rating" | "progress" | "survey" | "checklist";
-export type DataBlockType = "stats" | "comparison" | "chart" | "table";
-export type LegacyBlockType = "text" | "metric" | "chatbot" | "embed";
+export type NotificationBlockType = 'alert' | 'success' | 'warning' | 'info' | 'error';
+export type MediaBlockType = 'video' | 'gallery' | 'code';
+export type InteractiveBlockType = 'form' | 'rating' | 'progress' | 'survey' | 'checklist';
+export type DataBlockType = 'stats' | 'comparison' | 'chart' | 'table';
+export type LegacyBlockType = 'text' | 'metric' | 'chatbot' | 'embed';
 /**
  * Union of all block types
  */
-export type BlockType = NotificationBlockType | MediaBlockType | InteractiveBlockType | DataBlockType | LegacyBlockType | "custom";
+export type BlockType = NotificationBlockType | MediaBlockType | InteractiveBlockType | DataBlockType | LegacyBlockType | 'custom';
 export interface NotificationContentBase {
     title: string;
     body?: string;
@@ -33,49 +47,49 @@ export interface NotificationContentBase {
     timestamp?: string;
 }
 export interface AlertContent extends NotificationContentBase {
-    type: "alert";
-    severity?: "low" | "medium" | "high" | "critical";
+    type: 'alert';
+    severity?: 'low' | 'medium' | 'high' | 'critical';
 }
 export interface SuccessContent extends NotificationContentBase {
-    type: "success";
+    type: 'success';
     confetti?: boolean;
 }
 export interface WarningContent extends NotificationContentBase {
-    type: "warning";
+    type: 'warning';
     countdown?: number;
 }
 export interface InfoContent extends NotificationContentBase {
-    type: "info";
+    type: 'info';
     learnMoreUrl?: string;
 }
 export interface ErrorContent extends NotificationContentBase {
-    type: "error";
+    type: 'error';
     errorCode?: string;
     retryable?: boolean;
 }
 export type NotificationContent = AlertContent | SuccessContent | WarningContent | InfoContent | ErrorContent;
 export interface VideoContent {
-    type: "video";
+    type: 'video';
     src: string;
-    provider?: "youtube" | "vimeo" | "custom";
+    provider?: 'youtube' | 'vimeo' | 'custom';
     poster?: string;
     autoplay?: boolean;
     muted?: boolean;
     loop?: boolean;
-    aspectRatio?: "16:9" | "4:3" | "1:1" | "9:16";
+    aspectRatio?: '16:9' | '4:3' | '1:1' | '9:16';
 }
 export interface GalleryContent {
-    type: "gallery";
+    type: 'gallery';
     images: Array<{
         src: string;
         alt?: string;
         caption?: string;
     }>;
-    layout?: "carousel" | "grid" | "masonry";
+    layout?: 'carousel' | 'grid' | 'masonry';
     columns?: 2 | 3 | 4;
 }
 export interface CodeContent {
-    type: "code";
+    type: 'code';
     code: string;
     language?: string;
     lineNumbers?: boolean;
@@ -86,7 +100,7 @@ export interface CodeContent {
 export type MediaContent = VideoContent | GalleryContent | CodeContent;
 export interface FormField {
     id: string;
-    type: "text" | "email" | "select" | "checkbox" | "radio" | "textarea";
+    type: 'text' | 'email' | 'select' | 'checkbox' | 'radio' | 'textarea';
     label: string;
     placeholder?: string;
     required?: boolean;
@@ -97,21 +111,21 @@ export interface FormField {
     defaultValue?: string | boolean;
 }
 export interface FormContent {
-    type: "form";
+    type: 'form';
     fields: FormField[];
     submitLabel?: string;
     submitActionId?: string;
 }
 export interface RatingContent {
-    type: "rating";
-    variant: "stars" | "thumbs" | "nps" | "emoji";
+    type: 'rating';
+    variant: 'stars' | 'thumbs' | 'nps' | 'emoji';
     question?: string;
     maxValue?: number;
     submitActionId?: string;
 }
 export interface ProgressContent {
-    type: "progress";
-    variant: "bar" | "steps" | "circular";
+    type: 'progress';
+    variant: 'bar' | 'steps' | 'circular';
     value: number;
     max?: number;
     steps?: Array<{
@@ -126,7 +140,7 @@ export interface SurveyChoice {
     icon?: string;
 }
 export interface SurveyContent {
-    type: "survey";
+    type: 'survey';
     question: string;
     choices: SurveyChoice[];
     multiSelect?: boolean;
@@ -143,19 +157,19 @@ export interface ChecklistItem {
     completed?: boolean;
 }
 export interface ChecklistContent {
-    type: "checklist";
+    type: 'checklist';
     items: ChecklistItem[];
     title?: string;
     showProgress?: boolean;
 }
 export type InteractiveContent = FormContent | RatingContent | ProgressContent | SurveyContent | ChecklistContent;
 export interface TrendIndicator {
-    direction: "up" | "down" | "neutral";
+    direction: 'up' | 'down' | 'neutral';
     value: string;
     timeframe?: string;
 }
 export interface StatsContent {
-    type: "stats";
+    type: 'stats';
     value: string;
     label: string;
     trend?: TrendIndicator;
@@ -170,15 +184,15 @@ export interface ComparisonItem {
     icon?: string;
 }
 export interface ComparisonContent {
-    type: "comparison";
+    type: 'comparison';
     items: ComparisonItem[];
-    layout?: "grid" | "list" | "table";
+    layout?: 'grid' | 'list' | 'table';
     columns?: 2 | 3 | 4;
     highlightBest?: boolean;
 }
 export interface ChartContent {
-    type: "chart";
-    chartType: "bar" | "line" | "pie" | "donut";
+    type: 'chart';
+    chartType: 'bar' | 'line' | 'pie' | 'donut';
     data: Array<{
         label: string;
         value: number;
@@ -195,7 +209,7 @@ export interface TableColumn {
     width?: string;
 }
 export interface TableContent {
-    type: "table";
+    type: 'table';
     columns: TableColumn[];
     rows: Array<Record<string, string | number>>;
     sortable?: boolean;
@@ -206,12 +220,12 @@ export type DataContent = StatsContent | ComparisonContent | ChartContent | Tabl
 /**
  * Grid width: "full" = spans both columns, "half" = one column
  */
-export type TileSize = "full" | "half";
+export type TileSize = 'full' | 'half';
 /**
  * Built-in tile types (convenience components we ship)
  * @deprecated Use BlockType instead
  */
-export type BuiltInTileType = "text" | "metric" | "chatbot" | "embed";
+export type BuiltInTileType = 'text' | 'metric' | 'chatbot' | 'embed';
 /**
  * Content configuration for built-in tile types
  * @deprecated Use specific content types (NotificationContent, MediaContent, etc.)
@@ -229,7 +243,7 @@ export interface BuiltInTileContent {
  * Content configuration for custom tile components
  */
 export interface CustomTileContent {
-    type: "custom";
+    type: 'custom';
     component: string;
     props?: Record<string, unknown>;
     actions?: TileAction[];
@@ -249,7 +263,7 @@ export interface TileAction {
     label: string;
     href?: string;
     onClickId?: string;
-    style?: "primary" | "secondary";
+    style?: 'primary' | 'secondary';
 }
 /**
  * Visual styling for tile chrome
@@ -269,7 +283,7 @@ export interface TileExperiment {
     variationValue?: string | number | boolean;
     predicate?: (value: unknown) => boolean;
 }
-export type { ActivationConfig, RouteFilter, DecisionStrategy } from "./decisions/types";
+export type { ActivationConfig, RouteFilter, DecisionStrategy } from './decisions/types';
 /**
  * Full tile configuration
  */
@@ -292,12 +306,11 @@ export interface TileConfig {
      * Activation configuration for conditional rendering.
      * Replaces the experiment field with more flexible context-aware decisions.
      */
-    activation?: import("./decisions/types").ActivationConfig;
+    activation?: import('./decisions/types').ActivationConfig;
 }
-import type { Patch } from "./hostPatcher/core/types";
+import type { ActionStep } from './actions/types';
 /**
  * Theme configuration for the SmartCanvas overlay.
- * These values are typically set from workspace settings after style selection.
  */
 export interface CanvasThemeConfig {
     name?: string;
@@ -310,35 +323,55 @@ export interface CanvasThemeConfig {
     borderRadius?: string;
     position?: 'left' | 'right';
 }
+/**
+ * Launcher button configuration.
+ */
 export interface LauncherConfig {
-    /** Label shown on the launcher button (default: "Adaptives") */
     label?: string;
-    /** Whether to animate the launcher to draw attention */
     animate?: boolean;
-    /** Animation style: "pulse" (default), "bounce", "glow" */
-    animationStyle?: "pulse" | "bounce" | "glow";
+    animationStyle?: 'pulse' | 'bounce' | 'glow';
 }
+/**
+ * Route filtering - control where canvas appears.
+ */
 export interface RoutesConfig {
-    /** Routes where the canvas should NOT appear (e.g., ["/login", "/signup"]) */
     exclude?: string[];
-    /** If specified, canvas ONLY appears on these routes */
     include?: string[];
 }
+/**
+ * Canvas configuration response.
+ *
+ * This is the complete config format. Actions are the single mechanism
+ * for all interventions: DOM modifications, tooltips, highlights, modals.
+ */
 export interface CanvasConfigResponse {
+    /**
+     * Schema version this config conforms to (e.g., "2.0", "2.1").
+     * Used for compatibility checking and automatic migration between versions.
+     * If omitted, defaults to "1.0" for backwards compatibility.
+     *
+     * @since 2.0.0
+     */
+    schemaVersion?: string;
+    /** Tiles to display in the canvas drawer */
     tiles: TileConfig[];
+    /**
+     * Actions to execute.
+     * This is the unified intervention format. Every DOM change, tooltip,
+     * highlight, or modal is an ActionStep.
+     */
+    actions: ActionStep[];
+    /** When the config was fetched */
     fetchedAt: string;
+    /** Optional version string for cache invalidation */
     configVersion?: string;
+    /** Display title for the canvas */
     canvasTitle?: string;
-    patches?: Patch[];
-    /** @deprecated Use overlayRecipes instead */
-    overlayRecipe?: import('./overlays/types').CanvasRecipe;
-    /** Multiple overlay recipes (tours) */
-    overlayRecipes?: import('./overlays/types').CanvasRecipe[];
-    /** SmartCanvas theme configuration from workspace settings */
+    /** Theme configuration */
     theme?: CanvasThemeConfig;
     /** Launcher button configuration */
     launcher?: LauncherConfig;
-    /** Route filtering - control where canvas appears */
+    /** Route filtering */
     routes?: RoutesConfig;
 }
 export type CanvasConfigFetcher = () => Promise<CanvasConfigResponse>;

package/dist/types.js

@@ -1,5 +1,18 @@
 // =============================================================================
-// TILE COMPONENT API
+// SDK VERSION CONSTANTS
 // =============================================================================
-export {};
+// Re-export SDK_VERSION from the auto-generated version file
+export { SDK_VERSION } from './version';
+/**
+ * SDK schema version in Major.Minor format (e.g., "2.0", "2.1").
+ * Used for compatibility checking between SDK and backend configs.
+ * Sent in X-SDK-Schema-Version header.
+ *
+ * Bump rules:
+ * - Major: Breaking changes (field removal, type changes)
+ * - Minor: Backwards-compatible additions (new optional fields)
+ *
+ * @since 2.0.0
+ */
+export const SDK_SCHEMA_VERSION = '2.0';
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,qBAAqB;AACrB,gFAAgF"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,wBAAwB;AACxB,gFAAgF;AAEhF,6DAA6D;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,13 @@
+/**
+ * SDK package version.
+ *
+ * This file is auto-generated at release time by `scripts/prepare-release.mjs`.
+ * The sentinel value below is overwritten with the real semver version
+ * during the semantic-release prepare phase.
+ *
+ * DO NOT import version from package.json — this constant is the single
+ * source of truth for the runtime bundle.
+ *
+ * @since 2.0.0
+ */
+export declare const SDK_VERSION = "1.0.0-canary.1";

package/dist/version.js

@@ -0,0 +1,14 @@
+/**
+ * SDK package version.
+ *
+ * This file is auto-generated at release time by `scripts/prepare-release.mjs`.
+ * The sentinel value below is overwritten with the real semver version
+ * during the semantic-release prepare phase.
+ *
+ * DO NOT import version from package.json — this constant is the single
+ * source of truth for the runtime bundle.
+ *
+ * @since 2.0.0
+ */
+export const SDK_VERSION = '1.0.0-canary.1';
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,gBAAgB,CAAC"}

package/dist/widgets/WidgetRegistry.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Widget Registry
+ *
+ * Extensible registry for mountable widget components.
+ * Apps can register custom widgets that can be rendered via mountWidget actions.
+ */
+/**
+ * Cleanup function returned when unmounting a widget.
+ */
+export type WidgetCleanup = () => void;
+/**
+ * Mountable widget component interface.
+ *
+ * Widgets must implement this interface to be registered and mounted
+ * via the Surfaces system or mountWidget actions.
+ */
+export interface MountableWidget {
+    /**
+     * Mount the widget into a container element.
+     *
+     * @param container - The DOM element to mount into
+     * @param config - Configuration/props for the widget
+     * @returns A cleanup function to unmount the widget, or void
+     */
+    mount(container: HTMLElement, config?: Record<string, unknown>): WidgetCleanup | void;
+    /**
+     * Optional: Update the widget with new config.
+     * If not provided, the widget will be unmounted and remounted on updates.
+     *
+     * @param container - The DOM element containing the widget
+     * @param config - New configuration/props
+     */
+    update?(container: HTMLElement, config?: Record<string, unknown>): void;
+}
+/**
+ * Widget registration entry.
+ */
+export interface WidgetRegistration {
+    /** Widget ID (e.g., "gamification:leaderboard") */
+    id: string;
+    /** The widget component */
+    widget: MountableWidget;
+    /** Source app ID or "built-in" */
+    source: 'built-in' | string;
+    /** Optional metadata */
+    metadata?: {
+        name?: string;
+        description?: string;
+        icon?: string;
+    };
+}
+/**
+ * Mounted widget handle.
+ */
+export interface MountedWidgetHandle {
+    /** The widget ID */
+    widgetId: string;
+    /** The container element */
+    container: HTMLElement;
+    /** Unmount the widget */
+    unmount: () => void;
+    /** Update the widget config */
+    update: (config?: Record<string, unknown>) => void;
+}
+/**
+ * Extensible registry for widget components.
+ *
+ * Allows apps to register custom widgets that can be rendered via
+ * mountWidget actions or directly through the Surfaces system.
+ */
+export declare class WidgetRegistry {
+    private widgets;
+    private mountedWidgets;
+    private mountIdCounter;
+    constructor();
+    /**
+     * Register a widget.
+     *
+     * @param id - The widget ID (e.g., "gamification:leaderboard")
+     * @param widget - The widget component
+     * @param source - The source app ID (for tracking)
+     * @param metadata - Optional metadata about the widget
+     */
+    register(id: string, widget: MountableWidget, source?: string, metadata?: WidgetRegistration['metadata']): void;
+    /**
+     * Unregister a widget.
+     *
+     * @param id - The widget ID to unregister
+     * @returns true if the widget was unregistered, false if not found or built-in
+     */
+    unregister(id: string): boolean;
+    /**
+     * Unregister all widgets from a specific source.
+     *
+     * @param source - The source app ID
+     */
+    unregisterBySource(source: string): void;
+    /**
+     * Get a widget by ID.
+     */
+    get(id: string): MountableWidget | undefined;
+    /**
+     * Get the full registration for a widget.
+     */
+    getRegistration(id: string): WidgetRegistration | undefined;
+    /**
+     * Check if a widget exists.
+     */
+    has(id: string): boolean;
+    /**
+     * Mount a widget into a container.
+     *
+     * @param id - The widget ID
+     * @param container - The DOM element to mount into
+     * @param config - Configuration/props for the widget
+     * @returns A handle for managing the mounted widget
+     */
+    mount(id: string, container: HTMLElement, config?: Record<string, unknown>): MountedWidgetHandle;
+    /**
+     * List all registered widget IDs.
+     */
+    list(): string[];
+    /**
+     * List all registrations.
+     */
+    listRegistrations(): WidgetRegistration[];
+    /**
+     * Get all widgets from a specific source.
+     */
+    getBySource(source: string): WidgetRegistration[];
+    /**
+     * Clean up all mounted widgets.
+     */
+    destroy(): void;
+}
+/**
+ * Default singleton instance of WidgetRegistry.
+ */
+export declare const widgetRegistry: WidgetRegistry;