infaira-canvas 0.1.9

package/templates/ican.d.ts

@@ -0,0 +1,763 @@
+/**
+ * ICan Components — TypeScript declarations
+ * InfAIra Canvas v2.0
+ *
+ * Canonical mirror of widget-bridge.ts (the runtime).
+ * Keep in sync with apps_frontend/src/microservices/ican/widget-bridge.ts.
+ *
+ * Every ICan component supports two universal props:
+ *   - className?: string             — adds a CSS class to the root element
+ *   - style?: React.CSSProperties    — merges with the component's base inline styles (yours wins)
+ */
+
+declare module "ican/components" {
+  import * as React from "react";
+
+  // ─── Shared primitives ──────────────────────────────────────────────────────
+
+  export type ICanVariant = "primary" | "secondary" | "danger" | "ghost";
+  export type ICanBadgeVariant = "default" | "success" | "warning" | "error" | "info";
+  export type ICanSize = "xs" | "sm" | "md" | "lg";
+  export type ICanPosition = "top" | "bottom" | "left" | "right";
+  export type ICanDropdownPosition = "bottom-left" | "bottom-right" | "top-left" | "top-right";
+  export type ICanIconType =
+    | "search" | "close" | "done" | "edit" | "delete" | "add"
+    | "filter" | "arrow-up" | "arrow-down" | "arrow-left" | "arrow-right"
+    | "pin" | "copy" | "refresh";
+
+  export interface ICanOption { label: string; value: string; }
+
+  /** Universal styling props supported by every ICan component. */
+  export interface ICanStyledProps {
+    className?: string;
+    style?: React.CSSProperties;
+  }
+
+  // ─── Layout ────────────────────────────────────────────────────────────────
+
+  export interface IWidgetWrapperProps extends ICanStyledProps {
+    children: React.ReactNode;
+  }
+  export const WidgetWrapper: React.FC<IWidgetWrapperProps>;
+
+  export interface ILoadingProps extends ICanStyledProps { label?: string; }
+  export const Loading: React.FC<ILoadingProps>;
+
+  export interface ITitleBarProps extends ICanStyledProps {
+    title: string;
+    subtitle?: string;
+    children?: React.ReactNode;
+  }
+  export const TitleBar: React.FC<ITitleBarProps>;
+
+  export interface IFilterPanelProps extends ICanStyledProps { children?: React.ReactNode; }
+  export const FilterPanel: React.FC<IFilterPanelProps>;
+
+  export interface IErrorDisplayProps extends ICanStyledProps { message: string; }
+  export const ErrorDisplay: React.FC<IErrorDisplayProps>;
+
+  export interface ICardProps extends ICanStyledProps {
+    children?: React.ReactNode;
+    /** Optional header slot rendered above children with a divider. */
+    header?: React.ReactNode;
+    /** Optional footer slot rendered below children with a divider. */
+    footer?: React.ReactNode;
+  }
+  export const Card: React.FC<ICardProps>;
+
+  export interface IDataListProps extends ICanStyledProps {
+    items: Array<{ label: string; value: string | number }>;
+  }
+  export const DataList: React.FC<IDataListProps>;
+
+  // ─── Buttons ───────────────────────────────────────────────────────────────
+
+  export interface IButtonProps extends ICanStyledProps {
+    label: string;
+    onClick: () => void;
+    variant?: ICanVariant;
+    size?: "sm" | "md" | "lg";
+    disabled?: boolean;
+    loading?: boolean;
+    /** Optional icon (string/emoji or any React node) rendered before the label. */
+    icon?: React.ReactNode;
+  }
+  export const Button: React.FC<IButtonProps>;
+
+  export interface IAsyncButtonProps extends ICanStyledProps {
+    label: string;
+    onClick: () => Promise<void>;
+    icon?: string;
+    loadingLabel?: string;
+    disabled?: boolean;
+    variant?: "primary" | "secondary" | "danger";
+  }
+  export const AsyncButton: React.FC<IAsyncButtonProps>;
+
+  export interface IConfirmButtonProps extends ICanStyledProps {
+    label: string;
+    confirmLabel?: string;
+    onConfirm: () => Promise<void>;
+    variant?: "primary" | "danger";
+    disabled?: boolean;
+  }
+  export const ConfirmButton: React.FC<IConfirmButtonProps>;
+
+  export interface IIconButtonProps extends ICanStyledProps {
+    type: ICanIconType;
+    onClick: () => void;
+    active?: boolean;
+    disabled?: boolean;
+    size?: "sm" | "md" | "lg";
+    tooltip?: string;
+  }
+  export const IconButton: React.FC<IIconButtonProps>;
+
+  // ─── Form inputs ───────────────────────────────────────────────────────────
+
+  export interface IInputProps extends ICanStyledProps {
+    value: string;
+    onChange: (v: string) => void;
+    placeholder?: string;
+    label?: string;
+    type?: string;
+    disabled?: boolean;
+    error?: string;
+  }
+  export const Input: React.FC<IInputProps>;
+
+  export interface ITextAreaProps extends ICanStyledProps {
+    value: string;
+    onChange: (v: string) => void;
+    placeholder?: string;
+    label?: string;
+    rows?: number;
+    disabled?: boolean;
+    error?: string;
+    maxLength?: number;
+  }
+  export const TextArea: React.FC<ITextAreaProps>;
+
+  export interface ISelectProps extends ICanStyledProps {
+    value: string;
+    onChange: (v: string) => void;
+    options: ICanOption[];
+    placeholder?: string;
+    label?: string;
+    disabled?: boolean;
+  }
+  export const Select: React.FC<ISelectProps>;
+
+  export interface ICheckboxProps extends ICanStyledProps {
+    checked: boolean;
+    onChange: (v: boolean) => void;
+    label?: string;
+    type?: "default" | "bordered" | "switch" | "toggle" | "indicator";
+    disabled?: boolean;
+  }
+  export const Checkbox: React.FC<ICheckboxProps>;
+
+  export interface IMultiSelectProps extends ICanStyledProps {
+    options: ICanOption[];
+    selected: string[];
+    onChange: (values: string[]) => void;
+    placeholder?: string;
+    label?: string;
+    searchable?: boolean;
+    maxHeight?: string;
+  }
+  export const MultiSelect: React.FC<IMultiSelectProps>;
+
+  export interface IToggleFilterProps extends ICanStyledProps {
+    options: ICanOption[];
+    value: string;
+    onChange: (v: string) => void;
+    size?: "sm" | "md";
+  }
+  export const ToggleFilter: React.FC<IToggleFilterProps>;
+
+  export interface IColorPickerProps extends ICanStyledProps {
+    color: string;
+    onChange: (color: string) => void;
+    label?: string;
+    presets?: string[];
+  }
+  export const ColorPicker: React.FC<IColorPickerProps>;
+
+  export interface ISearchInputProps extends ICanStyledProps {
+    value: string;
+    onChange: (v: string) => void;
+    placeholder?: string;
+    onClear?: () => void;
+  }
+  export const SearchInput: React.FC<ISearchInputProps>;
+
+  export interface IFormFieldProps extends ICanStyledProps {
+    label?: string;
+    hint?: string;
+    error?: string;
+    required?: boolean;
+    inline?: boolean;
+    children?: React.ReactNode;
+  }
+  export const FormField: React.FC<IFormFieldProps>;
+
+  export interface ILabelProps extends ICanStyledProps {
+    required?: boolean;
+    children?: React.ReactNode;
+  }
+  export const Label: React.FC<ILabelProps>;
+
+  export interface IFormFeedbackProps extends ICanStyledProps {
+    validInput?: boolean;
+    children?: React.ReactNode;
+  }
+  export const FormFeedback: React.FC<IFormFeedbackProps>;
+
+  // ─── Date / time pickers (string-based ISO values) ─────────────────────────
+
+  export interface IDatePickerProps extends ICanStyledProps {
+    value: string | null;
+    onChange: (date: string) => void;
+    label?: string;
+    placeholder?: string;
+    minDate?: string;
+    maxDate?: string;
+    disabled?: boolean;
+  }
+  export const DatePicker: React.FC<IDatePickerProps>;
+
+  export interface ITimePickerProps extends ICanStyledProps {
+    value: string | null;
+    onChange: (time: string) => void;
+    label?: string;
+    placeholder?: string;
+    disabled?: boolean;
+  }
+  export const TimePicker: React.FC<ITimePickerProps>;
+
+  export interface IDateRangePickerProps extends ICanStyledProps {
+    startDate: string | null;
+    endDate: string | null;
+    onChange: (start: string, end: string) => void;
+    label?: string;
+    placeholder?: string;
+    disabled?: boolean;
+  }
+  export const DateRangePicker: React.FC<IDateRangePickerProps>;
+
+  export interface IDateTimePickerProps extends ICanStyledProps {
+    value: string | null;
+    onChange: (datetime: string) => void;
+    label?: string;
+    disabled?: boolean;
+  }
+  export const DateTimePicker: React.FC<IDateTimePickerProps>;
+
+  export interface ICalendarViewProps extends ICanStyledProps {
+    dates?: string[];
+    onSelectDate?: (date: string) => void;
+    minDate?: string;
+    maxDate?: string;
+  }
+  export const CalendarView: React.FC<ICalendarViewProps>;
+
+  // ─── Data Display ──────────────────────────────────────────────────────────
+
+  export interface IBadgeProps extends ICanStyledProps {
+    label: string;
+    variant?: ICanBadgeVariant;
+    dot?: boolean;
+  }
+  export const Badge: React.FC<IBadgeProps>;
+
+  export interface IStatCardProps extends ICanStyledProps {
+    label: string;
+    value: string | number;
+    unit?: string;
+    trend?: number;
+    icon?: string;
+    /** Small subtext rendered below the value (e.g. "vs last month"). */
+    description?: string;
+  }
+  export const StatCard: React.FC<IStatCardProps>;
+
+  export interface IEmptyStateProps extends ICanStyledProps {
+    title: string;
+    description?: string;
+    icon?: string;
+    action?: React.ReactNode;
+  }
+  export const EmptyState: React.FC<IEmptyStateProps>;
+
+  export interface IDataTableColumn {
+    key: string;
+    label: string;
+    width?: string;
+    render?: (value: unknown, row: Record<string, unknown>) => React.ReactNode;
+    /** When true, the column header is clickable and toggles asc/desc/off sorting. */
+    sortable?: boolean;
+  }
+  export interface IDataTableProps extends ICanStyledProps {
+    columns: IDataTableColumn[];
+    rows: Array<Record<string, unknown>>;
+    loading?: boolean;
+    emptyMessage?: string;
+    onRowClick?: (row: Record<string, unknown>) => void;
+    stickyHeader?: boolean;
+  }
+  export const DataTable: React.FC<IDataTableProps>;
+
+  export interface IDataGridProps extends ICanStyledProps {
+    items: unknown[];
+    renderItem: (item: unknown, index: number) => React.ReactNode;
+    columns?: number;
+    gap?: string;
+    loading?: boolean;
+    emptyMessage?: string;
+  }
+  export const DataGrid: React.FC<IDataGridProps>;
+
+  export interface IItemCardProps extends ICanStyledProps {
+    title: string;
+    subtitle?: string;
+    image?: string;
+    name?: string;
+    meta?: string;
+    onClick?: () => void;
+    actions?: React.ReactNode;
+  }
+  export const ItemCard: React.FC<IItemCardProps>;
+
+  export interface IItemListCardProps extends ICanStyledProps {
+    title: string;
+    subtitle?: string;
+    fields: Array<{ label: string; value: string | number | React.ReactNode }>;
+    actions?: React.ReactNode;
+    onClick?: () => void;
+  }
+  export const ItemListCard: React.FC<IItemListCardProps>;
+
+  export interface IHorizontalScrollListProps extends ICanStyledProps {
+    items: unknown[];
+    renderItem: (item: unknown, index: number) => React.ReactNode;
+    itemWidth?: string;
+  }
+  export const HorizontalScrollList: React.FC<IHorizontalScrollListProps>;
+
+  export interface INotificationBlockProps extends ICanStyledProps {
+    message: string;
+    type?: "info" | "success" | "warning" | "error";
+    onClose?: () => void;
+    icon?: string;
+    /** Optional bold heading rendered above the message. */
+    title?: string;
+  }
+  export const NotificationBlock: React.FC<INotificationBlockProps>;
+
+  export interface IProfileImageProps extends ICanStyledProps {
+    image?: string;
+    name: string;
+    size?: ICanSize;
+    bgColor?: string;
+  }
+  export const ProfileImage: React.FC<IProfileImageProps>;
+
+  export interface ISampleDataLabelProps extends ICanStyledProps { show?: boolean; }
+  export const SampleDataLabel: React.FC<ISampleDataLabelProps>;
+
+  // ─── Overlays ──────────────────────────────────────────────────────────────
+
+  export interface ITooltipProps extends ICanStyledProps {
+    content: string | React.ReactNode;
+    position?: ICanPosition;
+    children: React.ReactNode;
+    /** Delay in ms before the tooltip appears on hover. Default 200. */
+    delay?: number;
+  }
+  export const Tooltip: React.FC<ITooltipProps>;
+
+  export interface IPopoverProps extends ICanStyledProps {
+    trigger: React.ReactNode;
+    content: React.ReactNode;
+    position?: ICanPosition;
+    onOpen?: () => void;
+    onClose?: () => void;
+  }
+  export const Popover: React.FC<IPopoverProps>;
+
+  export interface IDropDownButtonProps extends ICanStyledProps {
+    label?: string;
+    icon?: string;
+    children: React.ReactNode;
+    position?: ICanDropdownPosition;
+    onOpen?: () => void;
+    onClose?: () => void;
+  }
+  export const DropDownButton: React.FC<IDropDownButtonProps>;
+
+  // ─── Tabs / Modal / Pagination ─────────────────────────────────────────────
+
+  export interface ITabConfig {
+    key: string;
+    label: string;
+  }
+  export interface ITabsProps extends ICanStyledProps {
+    tabs: ITabConfig[];
+    activeKey: string;
+    onChange: (key: string) => void;
+  }
+  export const Tabs: React.FC<ITabsProps>;
+
+  export interface IModalProps extends ICanStyledProps {
+    open: boolean;
+    onClose: () => void;
+    title?: string;
+    children: React.ReactNode;
+    footer?: React.ReactNode;
+    width?: string;
+    /** When false, disables Escape, X-button, and backdrop-click closing. Default true. */
+    closable?: boolean;
+  }
+  export const Modal: React.FC<IModalProps>;
+
+  export interface IPaginationProps extends ICanStyledProps {
+    page: number;
+    pageSize: number;
+    total: number;
+    onChange: (page: number) => void;
+  }
+  export const Pagination: React.FC<IPaginationProps>;
+
+  // ─── Wizard ────────────────────────────────────────────────────────────────
+
+  export interface IWizardStepRenderArgs {
+    next: () => void;
+    prev: () => void;
+    isFirst: boolean;
+    isLast: boolean;
+  }
+  export interface IWizardStep {
+    id: string;
+    title: string;
+    render: (args: IWizardStepRenderArgs) => React.ReactNode;
+    onNext?: () => boolean | Promise<boolean>;
+  }
+  export interface IWizardProps extends ICanStyledProps {
+    steps: IWizardStep[];
+    onComplete: () => void;
+    completionTitle?: string;
+  }
+  export const Wizard: React.FC<IWizardProps>;
+
+  export interface IModalWizardProps extends ICanStyledProps {
+    open: boolean;
+    onClose: () => void;
+    steps: IWizardStep[];
+    onComplete: () => void;
+    completionTitle?: string;
+    title?: string;
+    width?: string;
+  }
+  export const ModalWizard: React.FC<IModalWizardProps>;
+
+  // ─── Charts ────────────────────────────────────────────────────────────────
+
+  export interface IPieChartDataItem {
+    label: string;
+    value: number;
+    color?: string;
+  }
+  export interface IPieChartProps extends ICanStyledProps {
+    data: IPieChartDataItem[];
+    size?: number;
+    showLegend?: boolean;
+    donut?: boolean;
+    centerLabel?: string;
+  }
+  export const PieChart: React.FC<IPieChartProps>;
+
+  export interface ILineChartSeries {
+    label: string;
+    data: Array<{ x: string | number; y: number }>;
+    color?: string;
+    fill?: boolean;
+  }
+  export interface ILineChartProps extends ICanStyledProps {
+    series: ILineChartSeries[];
+    height?: number;
+    showGrid?: boolean;
+    showDots?: boolean;
+    xLabel?: string;
+    yLabel?: string;
+  }
+  export const LineChart: React.FC<ILineChartProps>;
+
+  export interface IBarChartDataItem {
+    label: string;
+    value: number;
+    color?: string;
+  }
+  export interface IBarChartProps extends ICanStyledProps {
+    data: IBarChartDataItem[];
+    height?: number;
+    horizontal?: boolean;
+    showValues?: boolean;
+    showGrid?: boolean;
+  }
+  export const BarChart: React.FC<IBarChartProps>;
+
+  export interface IRadialGaugeProps extends ICanStyledProps {
+    value: number;
+    min?: number;
+    max?: number;
+    label?: string;
+    unit?: string;
+    colors?: Array<{ color: string; stopAt: number }>;
+    size?: number;
+    thickness?: number;
+    showNeedle?: boolean;
+    animated?: boolean;
+  }
+  export const RadialGauge: React.FC<IRadialGaugeProps>;
+
+  // ─── Chart Loaders (skeletons) ─────────────────────────────────────────────
+
+  export interface IChartLoaderProps extends ICanStyledProps {
+    height?: number;
+    animated?: boolean;
+  }
+  export const ChartLoader: React.FC<IChartLoaderProps>;
+  export const BarChartLoader: React.FC<IChartLoaderProps>;
+  export const DonutChartLoader: React.FC<IChartLoaderProps>;
+  export const GaugeLoader: React.FC<IChartLoaderProps>;
+
+  // ─── Map ───────────────────────────────────────────────────────────────────
+
+  export interface IMapMarker {
+    lat: number;
+    lng: number;
+    popup?: string;
+    color?: string;
+  }
+  export interface IMapStaticImage {
+    url: string;
+    width: number;
+    height: number;
+  }
+  export interface IMapComponentProps extends ICanStyledProps {
+    center?: [number, number];
+    zoom?: number;
+    height?: string;
+    markers?: IMapMarker[];
+    onMarkerClick?: (marker: unknown) => void;
+    tileUrl?: string;
+    staticImage?: IMapStaticImage;
+  }
+  export const MapComponent: React.FC<IMapComponentProps>;
+}
+
+// ─── Hooks ────────────────────────────────────────────────────────────────────
+// ICan exposes a set of React hooks at runtime via global window slots.
+// Widgets can either declare these as webpack externals or use the canonical
+// import path "ican/hooks". The runtime resolves them to the portal's globals.
+
+declare module "ican/hooks" {
+  import * as React from "react";
+
+  // ─── useExecuteAction ─────────────────────────────────────────────────────
+  /**
+   * Returns a function that calls a registered model action on the current
+   * dashboard. Used by widgets to invoke server-side actions.
+   */
+  export function useExecuteAction(
+    dashboardId: string
+  ): (model: string, action: string, params?: Record<string, unknown>) => Promise<unknown>;
+
+  // ─── useMessageBus ────────────────────────────────────────────────────────
+  /**
+   * Subscribe to a pub/sub channel. The handler is invoked whenever any other
+   * widget calls publishMessage(channel, payload) on the same channel.
+   */
+  export type MessageHandler = (payload: unknown) => void;
+  export function useMessageBus(channel: string, handler: MessageHandler): void;
+  export function publishMessage(channel: string, payload: unknown): void;
+
+  // ─── useToast ─────────────────────────────────────────────────────────────
+  export interface IToastOptions {
+    duration?: number;
+    type?: "info" | "success" | "warning" | "error";
+    action?: { label: string; onClick: () => void };
+  }
+  export interface IToastHook {
+    show: (message: string, options?: IToastOptions) => void;
+    success: (message: string, options?: Omit<IToastOptions, "type">) => void;
+    error: (message: string, options?: Omit<IToastOptions, "type">) => void;
+    warning: (message: string, options?: Omit<IToastOptions, "type">) => void;
+    info: (message: string, options?: Omit<IToastOptions, "type">) => void;
+    dismiss: (id?: string) => void;
+  }
+  export function useToast(): IToastHook;
+
+  // ─── useAlert ─────────────────────────────────────────────────────────────
+  export interface IAlertHook {
+    confirm: (
+      title: string,
+      message?: string,
+      options?: { confirmLabel?: string; cancelLabel?: string; danger?: boolean }
+    ) => Promise<boolean>;
+    alert: (title: string, message?: string) => Promise<void>;
+    prompt: (
+      title: string,
+      message?: string,
+      options?: { defaultValue?: string; placeholder?: string }
+    ) => Promise<string | null>;
+  }
+  export function useAlert(): IAlertHook;
+
+  // ─── useDebounce ──────────────────────────────────────────────────────────
+  /**
+   * Returns a value that only updates after `delay` ms have elapsed since the
+   * last change. Useful for typing-driven search inputs and API calls.
+   */
+  export function useDebounce<T>(value: T, delay?: number): T;
+
+  // ─── usePolling ───────────────────────────────────────────────────────────
+  /**
+   * Calls `callback` on a fixed interval (`intervalMs`). Pause via the
+   * `paused` arg. The interval restarts each time deps change.
+   */
+  export function usePolling(
+    callback: () => void | Promise<void>,
+    intervalMs: number,
+    paused?: boolean
+  ): void;
+
+  // ─── useTranslation ───────────────────────────────────────────────────────
+  /**
+   * Returns the active locale and a translator function `t(key, default)`.
+   */
+  export function useTranslation(): {
+    t: (key: string, defaultValue: string) => string;
+    locale: string;
+  };
+  export function t(key: string, defaultValue: string): string;
+  export function setLocale(locale: string, dict: Record<string, string>): void;
+
+  // ─── useWidgetPrefs ───────────────────────────────────────────────────────
+  /**
+   * Persisted per-widget preferences. Returns [prefs, setPrefs] like useState
+   * but synced to the portal's prefs store keyed by `instanceId`.
+   */
+  export function useWidgetPrefs<T extends Record<string, unknown>>(
+    instanceId: string,
+    defaults: T
+  ): [T, (next: Partial<T>) => void];
+  export function clearWidgetPrefs(instanceId: string): void;
+
+  // ─── useFields ────────────────────────────────────────────────────────────
+  /**
+   * Lightweight controlled-form helper. Returns a getter/setter for each named
+   * field. Mirrors the UXP useFields hook for migrating widgets.
+   */
+  export function useFields<T extends Record<string, unknown>>(
+    initial: T
+  ): {
+    fields: T;
+    setField: <K extends keyof T>(name: K, value: T[K]) => void;
+    setFields: (next: Partial<T>) => void;
+    reset: () => void;
+  };
+
+  // ─── useResizeObserver ────────────────────────────────────────────────────
+  /**
+   * Returns the current size of the element referenced by `ref`. Updates
+   * automatically when the element's content box changes size.
+   */
+  export interface Size { width: number; height: number; }
+  export function useResizeObserver(ref: React.RefObject<HTMLElement>): Size;
+}
+
+// ─── Widget context type (passed to every widget as `icanContext` prop) ────────
+
+declare module "ican/context" {
+  /**
+   * The runtime context object every widget receives via the icanContext prop.
+   * Provides access to the portal's services from inside a widget bundle.
+   */
+  export interface IICanContext {
+    /** Stable id for this widget instance on the dashboard. */
+    instanceId: string;
+    /** Id of the dashboard the widget is rendered on. */
+    dashboardId: string;
+    /** Active theme name applied to the portal. */
+    theme: "light" | "dark" | "glass-dark" | "glass-light";
+    /** Locale string (e.g. "en", "es-ES"). */
+    locale: string;
+    /** Current authenticated user info, if available. */
+    user?: {
+      id: string;
+      name: string;
+      email?: string;
+      roles?: string[];
+    };
+    /** Invoke a registered model action on this dashboard. */
+    executeAction(
+      model: string,
+      action: string,
+      params?: Record<string, unknown>
+    ): Promise<unknown>;
+    /** Resolve a relative ICan backend path against the portal base URL. */
+    resolveUrl(path: string): string;
+    /** Logging helper namespaced to this widget instance. */
+    log(level: "info" | "warn" | "error", ...args: unknown[]): void;
+  }
+}
+
+// ─── Global runtime declarations ─────────────────────────────────────────────
+// These are set by widget-bridge.ts on the host portal and consumed by widget
+// bundles via webpack externals.
+//
+// This file is an ambient declaration (.d.ts with no top-level imports/exports
+// outside `declare module` blocks), so the `interface Window` below augments
+// the global Window type automatically.
+
+interface Window {
+  React: unknown;
+  ReactDOM: unknown;
+  ICanComponents: Record<string, unknown>;
+  UXPComponents: Record<string, unknown>;
+  WidgetDesignerComponents: Record<string, unknown>;
+  /** Widget registry — qualifiedId → registration entry. */
+  __ican_registry: Map<string, unknown>;
+  /** Widget registration handshake. Widgets call this after their script loads. */
+  registerWidget(registration: {
+    id: string;
+    component?: unknown;
+    /** UXP-legacy alias for `component`. */
+    widget?: unknown;
+    configs?: unknown;
+    defaultProps?: Record<string, unknown>;
+    label?: string;
+    name?: string;
+    description?: string;
+    icon?: string;
+  }): void;
+  __ican_messageBus?: {
+    useMessageBus: (channel: string, handler: (payload: unknown) => void) => void;
+    publishMessage: (channel: string, payload: unknown) => void;
+  };
+  __ican_i18n?: {
+    useTranslation: () => { t: (k: string, d: string) => string; locale: string };
+    t: (k: string, d: string) => string;
+    setLocale: (locale: string, dict: Record<string, string>) => void;
+  };
+  __ican_prefs?: {
+    useWidgetPrefs: <T extends Record<string, unknown>>(
+      instanceId: string,
+      defaults: T
+    ) => [T, (next: Partial<T>) => void];
+    clearWidgetPrefs: (instanceId: string) => void;
+  };
+  __ican_hooks?: Record<string, unknown>;
+}