@mgamadeus/ddd-agents 0.0.0-stage → 0.1.0-alpha.21

package/dist/types/preview/widget-preview-hydration.d.ts

@@ -0,0 +1,10 @@
+import type { WidgetPreviewResponse } from "./widget-preview.types";
+/**
+ * The preview's hydration transport for the `interactive` and `replay` modes: every registered hydrator is replaced by
+ * one that answers from the fixture's `hydration` (by derived key, else by type) and otherwise runs the real hydrator,
+ * whose requests the request transport answers from `responses`. The widget therefore runs its live code path —
+ * `useWidgetHydration` with the store's hydration slice, no frozen capture context — so a self-hydrating canvas widget
+ * auto-opens its canvas like in the chat (`CanvasWidgetCard`). The `email` mode keeps the capture's frozen hydration.
+ * Returns the disposer that puts the real hydrators back.
+ */
+export declare const installWidgetPreviewHydration: (hydration: Record<string, WidgetPreviewResponse>, onFailedRequest: (requestKey: string) => void) => (() => void);

package/dist/types/preview/widget-preview-readiness.d.ts

@@ -0,0 +1,27 @@
+import type { WidgetRenderReportEntry } from "../renderer/render-report/widget-render-report";
+import type { WidgetPreviewExpectedState } from "./widget-preview.types";
+/**
+ * The state an element shows — the same loading markers the e-mail capture refuses to shoot. `hasError` is true when
+ * the widget is known to be in an error: a failed hydration, a crash caught by the error boundary, or a request the
+ * fixture failed on purpose — a widget that renders nothing on an error would otherwise read as `empty`.
+ * `renderReport` is the block's own render report when the widget sent one: `failed` reads as `error`,
+ * `pending` as `loading` and `empty` as `empty` — a widget that shows one muted line ("No data to show.") for its empty
+ * state is empty, whatever text the line holds.
+ */
+export declare const observeWidgetPreviewState: (element: HTMLElement, hasError: boolean, renderReport?: WidgetRenderReportEntry) => WidgetPreviewExpectedState;
+/**
+ * The preview's ready signal: after every change it waits until the DOM is still for `SETTLE_MS`, then publishes what
+ * it shows — `window.__AGENTS_WIDGET_PREVIEW_V1__` (observed against the fixture's expected state, with every request
+ * the fixture had no response for) and the e-mail capture's `window.__AGENTS_WIDGET_IMAGE_V1__` (`ready` when the
+ * expected state was reached), so the same script conventions work for both. Both are also published under the names
+ * the app declares (`AgentsEnvironment.sandboxLegacyAliases`).
+ */
+export declare const createWidgetPreviewReadiness: (expectedState: WidgetPreviewExpectedState) => {
+    observe: (watchedElement: HTMLElement, widgetElement: HTMLElement, hasHydrationError: () => boolean) => () => void;
+    fail: (errorCode: string) => void;
+    recordMissingResponse: (requestKey: string) => void;
+    recordFailedRequest: (requestKey: string) => void;
+    recordWidgetCrash: () => void;
+    recordRenderReport: (entry: WidgetRenderReportEntry) => void;
+};
+export type WidgetPreviewReadiness = ReturnType<typeof createWidgetPreviewReadiness>;

package/dist/types/preview/widget-preview-requests.d.ts

@@ -0,0 +1,16 @@
+import type { WidgetPreviewResponse } from "./widget-preview.types";
+/** The key a fixture response is stored under: method, path and the sorted query (`GET /api/example/…?a=1&b=2`). */
+export declare const widgetPreviewRequestKey: (method: string, url: URL) => string;
+export declare const isStatusResponse: (response: unknown) => response is {
+    __status: number;
+    __body?: unknown;
+};
+export declare const isPendingResponse: (response: unknown) => boolean;
+/**
+ * Serves every request of the preview — axios and `fetch` — from the fixture: a known request gets its body (a copy), a
+ * `__status` entry fails with that status (a status of 400 or more is reported as a failed request — the error state the
+ * fixture asked for), a `__pending` entry never answers (the loading state), and anything else — an unknown read, a
+ * write the fixture does not answer — fails as a missing response and is reported. A write is answered only when the
+ * fixture names it (`"POST /api/example/…"`, e.g. a widget's fire-and-forget measurement event). Nothing reaches a server.
+ */
+export declare const installWidgetPreviewRequests: (responses: Record<string, WidgetPreviewResponse>, onMissingResponse: (requestKey: string) => void, onFailedRequest?: (requestKey: string) => void) => (() => void);

package/dist/types/preview/widget-preview-signal.d.ts

@@ -0,0 +1,10 @@
+import type { WidgetPreviewSignal } from "./widget-preview.types";
+/** The `window` property a preview script waits on. */
+export declare const WIDGET_PREVIEW_SIGNAL_GLOBAL_NAME = "__AGENTS_WIDGET_PREVIEW_V1__";
+/**
+ * Every name the preview signal is published under: the package's own, then each name the app declares
+ * (`AgentsEnvironment.sandboxLegacyAliases.previewReadinessGlobalNames`), read at each publish.
+ */
+export declare const readWidgetPreviewSignalGlobalNames: () => string[];
+/** Publishes (or with `undefined` clears) the preview signal under every name. */
+export declare const publishWidgetPreviewSignal: (signal: WidgetPreviewSignal | undefined) => void;

package/dist/types/preview/widget-preview.types.d.ts

@@ -0,0 +1,134 @@
+import type { WidgetRenderReportEntry } from "../renderer/render-report/widget-render-report";
+/**
+ * The widget preview: one registered widget — or a `ComposedView` tree — rendered outside the chat from
+ * a named fixture, in one of three modes, so a script can screenshot it, drive its interactions and compare it with the
+ * ChatGPT reference. The fixtures live next to each widget (`<kebab-name>.preview-fixtures.json`); the same dummy data
+ * can feed the widget's stories.
+ */
+/** `interactive`: the live reply (inputs work, canvases open); `replay`: a reloaded message; `email`: the capture look. */
+export type WidgetPreviewMode = "interactive" | "replay" | "email";
+/** What the fixture is built to show once it settles; the preview reports whether that state was reached. */
+export type WidgetPreviewExpectedState = "data" | "loading" | "empty" | "error";
+/** One step the compare script performs after the first screenshot (then it screenshots again). */
+export interface WidgetPreviewInteraction {
+    name: string;
+    /** Click the element with this visible text, or matching `selector`. */
+    click?: {
+        text?: string;
+        selector?: string;
+    };
+    /** Type `value` into the element matching `selector`. */
+    fill?: {
+        selector: string;
+        value: string;
+    };
+    /** Press one key (`Enter`, `ArrowRight`, …) on the focused element. */
+    press?: string;
+    /**
+     * Hover the element with this visible text, or matching `selector` — at `position` (CSS px from its top left corner)
+     * when given; with `position` alone the widget itself is hovered there (a chart point, a map marker).
+     */
+    hover?: {
+        text?: string;
+        selector?: string;
+        position?: {
+            x: number;
+            y: number;
+        };
+    };
+    /**
+     * The state this step must settle in, when it differs from the fixture's — the click that opens a detail whose read
+     * fails on purpose expects `error` while the chat block before it shows `data` (`scripts/widget-preview/preview-step-state.mjs`).
+     */
+    expectedState?: WidgetPreviewExpectedState;
+}
+/** A frozen GET response: the body, or a status the request fails with, or a request that never answers (loading). */
+export type WidgetPreviewResponse = unknown | {
+    __status: number;
+    __body?: unknown;
+} | {
+    __pending: true;
+};
+export interface WidgetPreviewFixture {
+    name: string;
+    description?: string;
+    /**
+     * The shared test data set the fixture's data comes from (e.g. `kassel-dental-practice`, one coherent customer across
+     * every domain) — read by the widget comparison manifest; the preview ignores it.
+     */
+    dataSet?: string;
+    /** The fence fields next to `type`. */
+    payload: Record<string, unknown>;
+    /**
+     * Hydrator type (or exact derived cache key) → the resolved result, as the e-mail capture takes it. In `email` mode it
+     * is the capture's frozen hydration; in `interactive` / `replay` the preview's hydrators answer with it (a value may
+     * be a `__status` or `__pending` entry like a response), so the widget runs its live code path — a self-hydrating
+     * canvas widget auto-opens its canvas. A hydrator type it does not name runs for real against `responses`.
+     */
+    hydration?: Record<string, WidgetPreviewResponse>;
+    /**
+     * `"GET /path?sorted=query"` → the response; a request with no entry fails as a missing response. A `__status`
+     * entry of 400 or more fails the request and makes the preview observe `error`.
+     */
+    responses?: Record<string, WidgetPreviewResponse>;
+    /** Location / project settings for the store, as the e-mail capture takes them. */
+    settings?: Record<string, unknown>;
+    /**
+     * The owner's language (`de`, `en`, `fr`, or a full `de-DE`) — the store's `GlobalReducer` language, so numbers and
+     * dates format as for that owner; the location's date locale follows unless `settings.location.localeFormatted` is
+     * set. Default `de`.
+     */
+    locale?: string;
+    expectedState?: WidgetPreviewExpectedState;
+    /** The chat width the screenshot is taken at; the script adds a narrow one. */
+    width?: number;
+    interactions?: WidgetPreviewInteraction[];
+    /** Render the kit's node types that have no component yet with the preview's stub components. */
+    stubComposedViewComponents?: boolean;
+    /**
+     * Parts of the URLs the browser fails to load on purpose (the picture of a broken-image fixture) — the render sweep
+     * (`scripts/widget-preview/render-sweep.mjs`) reports them as FAILED_ON_PURPOSE instead of REQUEST_FAILED.
+     */
+    expectedFailedRequests?: string[];
+}
+export interface WidgetPreviewFixtureFile {
+    wireName: string;
+    fixtures: WidgetPreviewFixture[];
+}
+export interface WidgetPreviewBootstrap {
+    widgetName: string;
+    fixtureName: string;
+    mode: WidgetPreviewMode;
+    width?: number;
+}
+/** What the page publishes for a script, beside the e-mail capture's `__AGENTS_WIDGET_IMAGE_V1__`. */
+export interface WidgetPreviewSignal {
+    version: 1;
+    state: "loading" | "settled" | "failed";
+    /** Bumped on every settle — after an interaction the script waits for the next revision. */
+    revision: number;
+    expectedState: WidgetPreviewExpectedState;
+    observedState?: WidgetPreviewExpectedState;
+    expectedStateReached?: boolean;
+    /** Requests the fixture has no response for (a harness gap, not a widget defect). */
+    missingResponses: string[];
+    /** Requests (and preview hydrations) the fixture answered with a failing `__status` — the error state it asked for. */
+    failedRequests: string[];
+    /** The widget threw and `ConversationWidgetErrorBoundary` caught it. */
+    widgetCrashed: boolean;
+    /** The block's last render report, when the widget sent one — the observed state follows it. */
+    renderReport?: WidgetRenderReportEntry;
+    error_code?: string;
+    rect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+declare global {
+    interface Window {
+        /** The preview's readiness signal (`publishWidgetPreviewSignal` also writes it under the app's declared names). */
+        __AGENTS_WIDGET_PREVIEW_V1__?: WidgetPreviewSignal;
+    }
+}

package/dist/types/provider/AgentsProvider.d.ts

@@ -0,0 +1,33 @@
+import { type ReactNode } from "react";
+import type { AgentsConversationClient } from "../client/AgentsConversationClient";
+import type { AgentsComponents } from "./components/types";
+import { type AgentsBudgetLimit, type AgentsEnvironment, type AgentsMapsLoaderState, type AgentsOwnerSettings, type AgentsStateAction, type AgentsTexts } from "./environment";
+export interface AgentsProviderProps {
+    /** The subtree's environment; members it leaves out fall back to the app-wide one, then to the defaults. */
+    environment?: AgentsEnvironment;
+    /** The conversation client the chat below reads and sends through (the one required input of a chat). */
+    client?: AgentsConversationClient;
+    children: ReactNode;
+}
+/**
+ * Supplies an environment and the conversation client to one subtree. `<AgentsProvider client={client}><AgentChat />
+ * </AgentsProvider>` is a whole chat with the package defaults.
+ */
+export declare const AgentsProvider: (props: AgentsProviderProps) => import("react/jsx-runtime").JSX.Element;
+/** The components package code renders: the subtree's replacements over the app's over the package defaults. */
+export declare const useAgentsComponents: () => AgentsComponents;
+export declare const useAgentsTexts: () => AgentsTexts;
+/** The environment of this subtree: its own members over the app-wide ones. */
+export declare const useAgentsEnvironment: () => AgentsEnvironment;
+/** Reads from the state store (`AgentsEnvironment.stateStore`, else the package's default store). */
+export declare const useAgentsStateSelector: <Selected>(selector: (state: any) => Selected) => Selected;
+/** The dispatch of the state store (`AgentsEnvironment.stateStore`, else the package's default store). */
+export declare const useAgentsStateDispatch: () => ((action: AgentsStateAction) => unknown);
+/** The owner's language and the active agent space's date and time settings (`AgentsEnvironment.useOwnerSettings`). */
+export declare const useAgentsOwnerSettings: () => AgentsOwnerSettings;
+/** The key of the agent space the owner works in (`AgentsEnvironment.useActiveAgentSpaceKey`). */
+export declare const useAgentsActiveAgentSpaceKey: () => number | undefined;
+/** The map script loader's state (`AgentsEnvironment.useMapsLoader`). */
+export declare const useAgentsMapsLoader: () => AgentsMapsLoaderState;
+/** What the error card of a reached budget offers (`AgentsEnvironment.useBudgetLimit`). */
+export declare const useAgentsBudgetLimit: () => AgentsBudgetLimit;

package/dist/types/provider/class-names.d.ts

@@ -0,0 +1,7 @@
+type ClassNameValue = string | undefined | null | false | Readonly<Record<string, boolean | undefined | null>>;
+/**
+ * Joins the class names that are set, skipping empty and falsy values; an object adds each key whose value is truthy
+ * (`classNames(styles.card, { [styles.selected]: isSelected })`), in argument order, as the `classnames` package does.
+ */
+export declare const classNames: (...args: ClassNameValue[]) => string;
+export {};

package/dist/types/provider/components/default-components.d.ts

@@ -0,0 +1,3 @@
+import type { AgentsComponents } from "./types";
+/** The package default of every replaceable component. */
+export declare const DEFAULT_AGENTS_COMPONENTS: AgentsComponents;

package/dist/types/provider/components/icon-names.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The icons package code uses, by name. The list is the contract: an app's `Icon` replacement maps every name, the
+ * package default draws every name. Extend it only together with the default drawing. It holds the names package
+ * components draw and every name a composed `Icon` node may carry (`IconComposedViewNode::ICON_NAMES`).
+ */
+export declare const AGENTS_ICON_NAMES: readonly ["add", "ai", "arrowDown", "arrowLeft", "arrowRight", "arrowUp", "barChart", "browser", "budget", "business", "calendar", "caretDown", "caretLeft", "caretUp", "check", "clock", "close", "closeCanvas", "dash", "desktop", "details", "directions", "document", "download", "duplicate", "edit", "event", "exclamation", "google", "help", "home", "image", "info", "like", "lineChart", "link", "location", "lock", "lockOpen", "mail", "maps", "maximize", "message", "messageBad", "messageGood", "messageNeutral", "minimize", "mobile", "newTab", "news", "notification", "pause", "phone", "photo", "pinFilled", "play", "post", "prize", "question", "refresh", "remove", "search", "searchEngines", "settings", "shield", "sorting", "star", "starActive", "tablet", "tag", "text", "trash", "upload", "user", "visibility", "warning", "wizard"];
+export type AgentsIconName = (typeof AGENTS_ICON_NAMES)[number];
+/** Whether a string is a package icon name (a name a model or a record wrote). */
+export declare const isAgentsIconName: (value: unknown) => value is AgentsIconName;

package/dist/types/provider/components/index.d.ts

@@ -0,0 +1,39 @@
+import type { AgentsButtonProps, AgentsCheckboxProps, AgentsDateInputProps, AgentsGlowFrameProps, AgentsIconProps, AgentsInteractiveSurfaceProps, AgentsLoadingSpinnerProps, AgentsMapMarkerProps, AgentsMapProps, AgentsModalLayerProps, AgentsProgressBarProps, AgentsRadioGroupProps, AgentsRangeSliderProps, AgentsSelectProps, AgentsSkeletonProps, AgentsSplitViewProps, AgentsStatusBadgeProps, AgentsTabsProps, AgentsTextAreaProps, AgentsTextInputProps, AgentsTextProps, AgentsTooltipProps, AgentsTrendDeltaProps, AgentsHeroRowProps, AgentsHeroValueProps, AgentsWidgetTextProps, AgentsSkeletonTextProps, AgentsStatusChipProps, AgentsSegmentBarProps, AgentsMarkdownProps, AgentsWidgetFeatureGateProps, AgentsConversationSearchResultsListProps } from "./types";
+/**
+ * The components package code imports. Each renders the app's replacement when the environment has one, else the
+ * package default — package code never imports an app's component library.
+ */
+export declare const Text: (props: AgentsTextProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Button: (props: AgentsButtonProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Icon: (props: AgentsIconProps) => import("react/jsx-runtime").JSX.Element;
+export declare const InteractiveSurface: (props: AgentsInteractiveSurfaceProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Skeleton: (props: AgentsSkeletonProps) => import("react/jsx-runtime").JSX.Element;
+export declare const LoadingSpinner: (props: AgentsLoadingSpinnerProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Tooltip: (props: AgentsTooltipProps) => import("react/jsx-runtime").JSX.Element;
+export declare const GlowFrame: (props: AgentsGlowFrameProps) => import("react/jsx-runtime").JSX.Element;
+export declare const ProgressBar: (props: AgentsProgressBarProps) => import("react/jsx-runtime").JSX.Element;
+export declare const SplitView: (props: AgentsSplitViewProps) => import("react/jsx-runtime").JSX.Element;
+export declare const TrendDelta: (props: AgentsTrendDeltaProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Checkbox: (props: AgentsCheckboxProps) => import("react/jsx-runtime").JSX.Element;
+export declare const TextInput: (props: AgentsTextInputProps) => import("react/jsx-runtime").JSX.Element;
+export declare const TextArea: (props: AgentsTextAreaProps) => import("react/jsx-runtime").JSX.Element;
+export declare const RangeSlider: (props: AgentsRangeSliderProps) => import("react/jsx-runtime").JSX.Element;
+export declare const DateInput: (props: AgentsDateInputProps) => import("react/jsx-runtime").JSX.Element;
+export declare const RadioGroup: (props: AgentsRadioGroupProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Select: (props: AgentsSelectProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Tabs: (props: AgentsTabsProps) => import("react/jsx-runtime").JSX.Element;
+export declare const StatusBadge: (props: AgentsStatusBadgeProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Map: (props: AgentsMapProps) => import("react/jsx-runtime").JSX.Element;
+export declare const MapMarker: (props: AgentsMapMarkerProps) => import("react/jsx-runtime").JSX.Element;
+export declare const ModalLayer: (props: AgentsModalLayerProps) => import("react/jsx-runtime").JSX.Element;
+export declare const HeroRow: (props: AgentsHeroRowProps) => import("react/jsx-runtime").JSX.Element;
+export declare const HeroValue: (props: AgentsHeroValueProps) => import("react/jsx-runtime").JSX.Element;
+export declare const WidgetText: (props: AgentsWidgetTextProps) => import("react/jsx-runtime").JSX.Element;
+export declare const SkeletonText: (props: AgentsSkeletonTextProps) => import("react/jsx-runtime").JSX.Element;
+export declare const StatusChip: (props: AgentsStatusChipProps) => import("react/jsx-runtime").JSX.Element;
+export declare const SegmentBar: (props: AgentsSegmentBarProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Markdown: (props: AgentsMarkdownProps) => import("react/jsx-runtime").JSX.Element;
+export declare const WidgetFeatureGate: (props: AgentsWidgetFeatureGateProps) => import("react/jsx-runtime").JSX.Element;
+export declare const ConversationSearchResultsList: (props: AgentsConversationSearchResultsListProps) => import("react/jsx-runtime").JSX.Element;
+export type * from "./types";
+export { AGENTS_ICON_NAMES, isAgentsIconName } from "./icon-names";