@syntrologie/runtime-sdk 1.0.1 → 2.0.0

package/dist/actions/types.d.ts

@@ -0,0 +1,399 @@
+/**
+ * ActionEngine Types
+ *
+ * Defines the types for the unified execution layer for interventions
+ * (highlight, tooltip, badge, DOM modifications, navigation).
+ */
+import type { Placement } from "@floating-ui/dom";
+/** Static surface slots with fixed positioning */
+export type StaticSurfaceSlot = "drawer_right" | "drawer_left" | "drawer_bottom" | "overlay_center" | "overlay_corner_br" | "overlay_corner_bl" | "toast_top" | "toast_bottom";
+/** Dynamic inline slot (rendered inside anchor) */
+export type InlineSurfaceSlot = `inline:${string}`;
+/** Dynamic adjacent slot (positioned near anchor) */
+export type AdjacentSurfaceSlot = `adjacent:${string}`;
+/** All surface slot types */
+export type SurfaceSlot = StaticSurfaceSlot | InlineSurfaceSlot | AdjacentSurfaceSlot;
+/** Highlight style configuration */
+export interface HighlightStyle {
+    /** Ring color (default: "#5b8cff") */
+    color?: string;
+    /** Backdrop scrim opacity 0-1 (default: 0.55, set to 0 to hide) */
+    scrimOpacity?: number;
+    /** Space between element and ring in pixels (default: 12) */
+    paddingPx?: number;
+    /** Ring corner radius in pixels (default: 12) */
+    radiusPx?: number;
+}
+/** Badge position relative to anchor */
+export type BadgePosition = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+/** CTA button configuration for tooltips/modals */
+export interface CtaButton {
+    label: string;
+    actionId: string;
+    primary?: boolean;
+}
+/** Modal content configuration */
+export interface ModalContent {
+    title?: string;
+    body: string;
+}
+/** Tooltip content configuration */
+export interface TooltipContent {
+    title?: string;
+    body: string;
+    cta?: {
+        label: string;
+        action: ActionStep;
+    };
+    ctaButtons?: CtaButton[];
+}
+/** Tooltip trigger mode */
+export type TooltipTrigger = "immediate" | "hover" | "click";
+/** Position where HTML/content should be inserted */
+export type InsertPosition = "before" | "after" | "prepend" | "append" | "replace";
+/** Widget configuration for surface mounting */
+export interface WidgetConfig {
+    widgetId: string;
+    props?: Record<string, unknown>;
+    priority?: number;
+}
+/** Base action with common properties */
+interface BaseAction {
+    /** Optional label for debugging/telemetry */
+    label?: string;
+}
+/** Highlight an anchor element with spotlight effect */
+export interface HighlightAction extends BaseAction {
+    kind: "overlays:highlight";
+    anchorId: string;
+    style?: HighlightStyle;
+    /** Duration in ms before auto-cleanup (for use in sequences) */
+    duration?: number;
+}
+/** Pulse animation on an anchor element */
+export interface PulseAction extends BaseAction {
+    kind: "overlays:pulse";
+    anchorId: string;
+    duration?: number;
+}
+/** Add a badge near an anchor element */
+export interface BadgeAction extends BaseAction {
+    kind: "overlays:badge";
+    anchorId: string;
+    content: string;
+    position?: BadgePosition;
+}
+/** Tooltip lifecycle - when the action completes (for sequences) */
+export type TooltipWaitFor = "dismissed" | "cta-click" | `timeout:${number}`;
+/** Show a tooltip near an anchor element */
+export interface TooltipAction extends BaseAction {
+    kind: "overlays:tooltip";
+    anchorId: string;
+    content: TooltipContent;
+    trigger?: TooltipTrigger;
+    placement?: Placement;
+    /** When the action completes (for use in sequences). Publishes event to EventBus. */
+    waitFor?: TooltipWaitFor;
+}
+/** Modal lifecycle - when the action completes (for sequences) */
+export type ModalWaitFor = "dismissed" | "cta-click" | `timeout:${number}`;
+/** Show a centered modal dialog */
+export interface ModalAction extends BaseAction {
+    kind: "overlays:modal";
+    content: ModalContent;
+    size?: "sm" | "md" | "lg";
+    blocking?: boolean;
+    scrim?: {
+        opacity?: number;
+    };
+    dismiss?: {
+        onEsc?: boolean;
+        closeButton?: boolean;
+        timeoutMs?: number;
+    };
+    ctaButtons?: CtaButton[];
+    /** When the action completes (for use in sequences). Publishes event to EventBus. */
+    waitFor?: ModalWaitFor;
+}
+/** Insert HTML content relative to anchor */
+export interface InsertHtmlAction extends BaseAction {
+    kind: "content:insertHtml";
+    anchorId: string;
+    html: string;
+    position: InsertPosition;
+}
+/** Set text content of an anchor */
+export interface SetTextAction extends BaseAction {
+    kind: "content:setText";
+    anchorId: string;
+    text: string;
+}
+/** Set an attribute on an anchor */
+export interface SetAttrAction extends BaseAction {
+    kind: "content:setAttr";
+    anchorId: string;
+    attr: string;
+    value: string;
+}
+/** Add a CSS class to an anchor */
+export interface AddClassAction extends BaseAction {
+    kind: "content:addClass";
+    anchorId: string;
+    className: string;
+}
+/** Remove a CSS class from an anchor */
+export interface RemoveClassAction extends BaseAction {
+    kind: "content:removeClass";
+    anchorId: string;
+    className: string;
+}
+/** Set inline styles on an anchor */
+export interface SetStyleAction extends BaseAction {
+    kind: "content:setStyle";
+    anchorId: string;
+    styles: Record<string, string>;
+}
+/** Mount a widget to a surface slot */
+export interface MountWidgetAction extends BaseAction {
+    kind: "core:mountWidget";
+    slot: SurfaceSlot;
+    widget: WidgetConfig;
+}
+/** Scroll to an anchor element */
+export interface ScrollToAction extends BaseAction {
+    kind: "navigation:scrollTo";
+    anchorId: string;
+    behavior?: ScrollBehavior;
+    block?: ScrollLogicalPosition;
+    inline?: ScrollLogicalPosition;
+}
+/** Navigate to a URL */
+export interface NavigateAction extends BaseAction {
+    kind: "navigation:navigate";
+    url: string;
+    target?: "_self" | "_blank";
+}
+/** Wait for a duration or an event on the EventBus */
+export interface WaitAction extends BaseAction {
+    kind: "core:wait";
+    /** Wait for a specific duration in milliseconds */
+    durationMs?: number;
+    /** Wait for an event on the EventBus */
+    event?: string;
+}
+/** Execute actions in sequence, awaiting each one's completion */
+export interface SequenceAction extends BaseAction {
+    kind: "core:sequence";
+    actions: ActionStep[];
+}
+/** Execute actions in parallel */
+export interface ParallelAction extends BaseAction {
+    kind: "core:parallel";
+    actions: ActionStep[];
+    /** How to determine completion: "all" waits for all, "any" completes when first finishes */
+    waitFor?: "all" | "any";
+}
+/** Tour step with route + action mapping */
+export interface TourStep {
+    id: string;
+    action: ActionStep;
+    route?: string;
+    onAction?: Record<string, string | "end">;
+}
+/** Orchestrate sequential steps with cross-page state */
+export interface TourAction extends BaseAction {
+    kind: "core:tour";
+    tourId: string;
+    steps: TourStep[];
+    startStep?: string;
+    autoStart?: boolean;
+}
+/** Union of all action step types */
+export type ActionStep = HighlightAction | PulseAction | BadgeAction | TooltipAction | ModalAction | InsertHtmlAction | SetTextAction | SetAttrAction | AddClassAction | RemoveClassAction | SetStyleAction | MountWidgetAction | ScrollToAction | NavigateAction | WaitAction | SequenceAction | ParallelAction | TourAction;
+/** Extract action kind literal types */
+export type ActionKind = ActionStep["kind"];
+/** State of an action */
+export type ActionState = "pending" | "applied" | "reverted" | "failed";
+/** Handle returned when an action is applied */
+export interface ActionHandle {
+    /** Unique ID for this action instance */
+    id: string;
+    /** The action that was applied */
+    action: ActionStep;
+    /** Revert the action */
+    revert: () => Promise<void>;
+    /** Check if action is still applied */
+    isApplied: () => boolean;
+    /** Update action in place (if supported) */
+    update: (changes: Partial<ActionStep>) => Promise<void>;
+    /** Get current state */
+    getState: () => ActionState;
+}
+/** Handle for batch action operations */
+export interface BatchActionHandle {
+    /** Unique ID for this batch */
+    id: string;
+    /** Individual action handles */
+    handles: ActionHandle[];
+    /** Revert all actions in the batch */
+    revertAll: () => Promise<void>;
+    /** Check if all actions are still applied */
+    isApplied: () => boolean;
+}
+/** Tracked active action */
+export interface ActiveAction {
+    /** Action ID */
+    id: string;
+    /** The action definition */
+    action: ActionStep;
+    /** Adaptive that owns this action */
+    adaptiveId?: string;
+    /** When the action was applied */
+    appliedTs: number;
+    /** Current state */
+    state: ActionState;
+}
+/** Validation error */
+export interface ValidationError {
+    code: string;
+    message: string;
+    field?: string;
+}
+/** Validation warning */
+export interface ValidationWarning {
+    code: string;
+    message: string;
+    suggestion?: string;
+}
+/** Result of validating an action */
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+}
+/** Cleanup function returned by executors */
+export type ExecutorCleanup = () => void | Promise<void>;
+/** Update function for actions that support in-place updates */
+export type ExecutorUpdate = (changes: Partial<ActionStep>) => void | Promise<void>;
+/** Result returned by action executors */
+export interface ExecutorResult {
+    /** Function to clean up/revert the action */
+    cleanup: ExecutorCleanup;
+    /** Optional function to update the action in place */
+    updateFn?: ExecutorUpdate;
+}
+/** Executor function signature */
+export type ActionExecutor<T extends ActionStep = ActionStep> = (action: T, context: ExecutorContext) => Promise<ExecutorResult>;
+/** Context passed to executors */
+export interface ExecutorContext {
+    /** Overlay root element for rendering */
+    overlayRoot: HTMLElement;
+    /** Resolve an anchor ID to an element */
+    resolveAnchor: (anchorId: string) => HTMLElement | null;
+    /** Generate unique IDs */
+    generateId: () => string;
+    /** Publish events to EventBus */
+    publishEvent: (name: string, props?: Record<string, unknown>) => void;
+    /** Get the current adaptive ID (if any) */
+    adaptiveId?: string;
+    /**
+     * Execute a nested action (for composite executors like tours).
+     * Returns a handle that can be used to revert the action.
+     */
+    applyAction?: (action: ActionStep) => Promise<ActionHandle>;
+    /**
+     * Subscribe to events (for composite executors).
+     * Returns an unsubscribe function.
+     */
+    subscribeEvent?: (name: string, callback: (props?: Record<string, unknown>) => void) => () => void;
+}
+/** Executor registry interface (subset needed by ActionEngine) */
+export interface ActionEngineExecutorRegistry {
+    get: (kind: string) => ActionExecutor<ActionStep> | undefined;
+    has: (kind: string) => boolean;
+}
+/** Options for creating an ActionEngine */
+export interface ActionEngineOptions {
+    /** Overlay root element */
+    overlayRoot: HTMLElement;
+    /** Event bus for publishing and subscribing to action events */
+    eventBus?: {
+        publish: (name: string, props?: Record<string, unknown>) => void;
+        subscribe: (filter: {
+            names?: string[];
+            patterns?: string[];
+        }, callback: (event: {
+            name: string;
+            props?: Record<string, unknown>;
+        }) => void) => () => void;
+    };
+    /** Surfaces provider for mountWidget actions */
+    surfaces?: {
+        mount: (slot: SurfaceSlot, content: RenderableContent, opts?: MountOptions) => MountHandle;
+    };
+    /** Function to resolve anchor IDs to elements */
+    anchorResolver: (anchorId: string) => HTMLElement | null;
+    /** Current adaptive ID for attribution */
+    adaptiveId?: string;
+    /** Optional executor registry (uses default singleton if not provided) */
+    executorRegistry?: ActionEngineExecutorRegistry;
+}
+/** The ActionEngine interface */
+export interface ActionEngine {
+    /** Apply a single action */
+    apply: (action: ActionStep) => Promise<ActionHandle>;
+    /** Apply multiple actions atomically */
+    applyBatch: (actions: ActionStep[]) => Promise<BatchActionHandle>;
+    /** Validate an action before applying */
+    validate: (action: ActionStep) => ValidationResult;
+    /** Get all currently active actions */
+    getActive: () => ActiveAction[];
+    /** Clean up all active actions and resources */
+    destroy: () => void;
+}
+/** Renderable content types for surfaces */
+export type RenderableContent = {
+    type: "react";
+    component: unknown;
+    props?: Record<string, unknown>;
+} | {
+    type: "html";
+    content: string;
+} | {
+    type: "widget";
+    widgetId: string;
+    config?: Record<string, unknown>;
+} | {
+    type: "custom";
+    mount: (container: HTMLElement) => () => void;
+};
+/** Mount options for surfaces */
+export interface MountOptions {
+    priority?: number;
+    exclusive?: boolean;
+    animation?: "fade" | "slide" | "scale" | "none";
+    position?: {
+        placement: Placement | "auto";
+        offset?: {
+            x: number;
+            y: number;
+        };
+        flip?: boolean;
+        shift?: boolean;
+    };
+    constraints?: {
+        maxWidth?: string;
+        maxHeight?: string;
+        minWidth?: string;
+        minHeight?: string;
+    };
+}
+/** Mount handle returned by Surfaces */
+export interface MountHandle {
+    update: (content: RenderableContent) => void;
+    setOptions: (opts: Partial<MountOptions>) => void;
+    unmount: () => void;
+    isMounted: () => boolean;
+    getContainer: () => HTMLElement | null;
+}
+export {};

package/dist/actions/types.js

@@ -0,0 +1,8 @@
+/**
+ * ActionEngine Types
+ *
+ * Defines the types for the unified execution layer for interventions
+ * (highlight, tooltip, badge, DOM modifications, navigation).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/actions/types.js.map

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

package/dist/actions/validation.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Action Validation
+ *
+ * Validates action steps before execution.
+ */
+import type { ActionStep, ValidationResult } from "./types";
+/**
+ * Validate an action step.
+ */
+export declare function validateAction(action: ActionStep): ValidationResult;
+/**
+ * Validate a batch of actions.
+ */
+export declare function validateActions(actions: ActionStep[]): ValidationResult;