@ai-matrx/alchemy 0.12.3 → 0.13.0

package/dist/react-workspace.d.cts

@@ -0,0 +1,441 @@
+import * as React from 'react';
+import { AgentPayloadInput, Payload, Artifact, TransferOutcome, FormatAdapter, PageAction, AiPreparation, Transport, TransferPreferenceOverrides, Source, ExportProjection, Section, SurfaceHandle, TransferScope } from '@ai-matrx/alchemy/operate';
+import { AlchemyIcon } from '@ai-matrx/design-system/content-transfer/icon';
+export { ALCHEMY_COPY_TRANSFORM_SVG, ALCHEMY_GLYPH_SVG, AlchemyIcon } from '@ai-matrx/design-system/content-transfer/icon';
+import { ContentTransferReference, TableCopyController, CopyControlProps } from '@ai-matrx/design-system/data-table/host';
+export { ContentTransferReference } from '@ai-matrx/design-system/data-table/host';
+
+/**
+ * Host levers (Preparation parity PP-02, PP-03, PP-05): the controls a screen declares for its own
+ * data — "tool results", "last N messages", "per-message cap", a groomer section's Full / Compact /
+ * Brief / Off — and how a lever value becomes the payload the workspace prepares.
+ *
+ * The levers live INSIDE the one preparation workspace, beside the preview: changing one rebuilds
+ * the payload from the host builder and the preview follows. There is no second dialog and no
+ * "Prepare in Alchemy" handoff that loses them.
+ *
+ * Text stays text (PP-09): a builder that returns text becomes a text payload whose AI envelope
+ * carries it as `<data format="text">`, never one escaped JSON string.
+ */
+
+type AlchemyOptionValues = Record<string, boolean | number>;
+type AlchemySourceOption = {
+    kind: "toggle";
+    key: string;
+    label: string;
+    hint?: string;
+    default: boolean;
+} | {
+    kind: "preset";
+    key: string;
+    label: string;
+    options: {
+        label: string;
+        value: number;
+    }[];
+    default: number;
+} | {
+    kind: "slider";
+    key: string;
+    label: string;
+    hint?: string;
+    stops: number[];
+    default: number;
+    formatValue: (value: number) => string;
+} | {
+    kind: "number";
+    key: string;
+    label: string;
+    hint?: string;
+    min?: number;
+    step?: number;
+    presets?: {
+        label: string;
+        value: number;
+    }[];
+    default: number;
+};
+type LeverMeta = Record<string, string | number | boolean | undefined>;
+interface AlchemyCustomSource {
+    label?: string;
+    hint?: string;
+    options: AlchemySourceOption[];
+    build(values: AlchemyOptionValues): {
+        text: string;
+        meta?: LeverMeta;
+    };
+    wrap(text: string, values: AlchemyOptionValues, meta?: LeverMeta): AgentPayloadInput;
+    dialogTitle?: string;
+    dialogDescription?: string;
+}
+type AlchemyDetail = "full" | "compact" | "brief";
+interface AlchemyGroomerSection {
+    id: string;
+    title: string;
+    description?: string;
+    cuttable?: boolean;
+    levelLabels?: Partial<Record<AlchemyDetail, string>>;
+    build(level: AlchemyDetail): unknown;
+    defaultSelection?: AlchemyDetail | "off";
+}
+interface AlchemyGroomerConfig {
+    label: string;
+    kind: string;
+    location: string;
+    description: string;
+    attributes?: AgentPayloadInput["attributes"];
+    context?: AgentPayloadInput["context"];
+    summary?: string;
+    sections: AlchemyGroomerSection[];
+}
+/** Who a piece of content is, for the AI envelope — everything but the body. */
+type EnvelopeMeta = Omit<AgentPayloadInput, "data" | "dataFormat" | "instructions">;
+type LeverValue = boolean | number | string;
+type LeverValues = Record<string, LeverValue>;
+type SectionLevel = AlchemyDetail | "off";
+interface LeverBuild {
+    payload: Payload;
+    envelope: EnvelopeMeta;
+    meta?: LeverMeta;
+    /** Per groomer section: its size in the prepared JSON at its current level (PP-04). */
+    sectionSizes?: Record<string, number>;
+}
+/** The levers one workspace session carries: the host's controls and the one builder they feed. */
+interface WorkspaceLevers {
+    /** Source options (custom levers), shown in Settings. */
+    options?: readonly AlchemySourceOption[];
+    /** Groomer sections, shown in Structure with their level control. */
+    sections?: readonly AlchemyGroomerSection[];
+    initial: LeverValues;
+    build(values: LeverValues): LeverBuild;
+}
+/** Presets over groomer sections (O4's Everything / Balanced / Minimal). */
+type AlchemyGroomerPreset = "everything" | "balanced" | "minimal";
+declare function applyGroomerPreset(preset: AlchemyGroomerPreset, sections: readonly AlchemyGroomerSection[]): Record<string, SectionLevel>;
+
+type SerializableFormat = "plain" | "markdown" | "html" | "json" | "compact-json" | "csv" | "tsv";
+
+/**
+ * THE preparation workspace (Preparation parity PP-01b, PP-01c, PP-02, PP-03, PP-04, PP-09, PP-10).
+ *
+ * One surface: the source's structure (sections, groomer sections, columns and rows) on the left,
+ * ONE read-only preview of the exact sealed bytes in the middle, and the host's own levers,
+ * instructions, AI preparation and destinations on the right. The envelope toggle (Text / For AI)
+ * chooses the one artifact the preview shows and the one Copy writes — preview = copy = download.
+ *
+ * Frames: inside a host window (`ContentTransferCapabilities.window`, the host's `WindowPort`) the
+ * host draws the title bar and the close control; without one it is a near-full-screen dialog.
+ * Below 768px of its own width it is three tabs (Structure / Preview / Settings) with Copy in a
+ * footer every tab shares.
+ */
+
+/** Structural twin of `@ai-matrx/alchemy/ports` `WindowPort` (design-system sits below alchemy). */
+interface WorkspaceWindowHandle {
+    readonly instanceId: string;
+    close(): void;
+    focus(): void;
+    isOpen(): boolean;
+}
+interface WorkspaceWindowPort {
+    readonly presentation: "window" | "dialog";
+    readonly multiInstance: boolean;
+    open(render: (window: WorkspaceWindowHandle) => unknown, options: {
+        title: string;
+        size?: {
+            width: number;
+            height: number;
+        } | "full";
+        instanceId?: string;
+        onClose?: () => void;
+    }): WorkspaceWindowHandle;
+}
+
+type ContentTransferReferencePort = {
+    supports(reference: ContentTransferReference): boolean;
+    build(reference: ContentTransferReference): string | Promise<string>;
+};
+type ContentTransferEmailPort = {
+    send(artifact: Artifact, context: {
+        label: string;
+        signal: AbortSignal;
+    }): Promise<TransferOutcome>;
+};
+/** A sealed, projection-safe representation of a tabular draft's declared schema and values. */
+declare const tableSchemaFormat: FormatAdapter;
+/** Flat row JSON keyed by user-facing display labels, never raw table records. */
+declare const tableDataFormat: FormatAdapter;
+type TransferEmailAction = PageAction & {
+    prepared: true;
+    group: "email";
+};
+/** Prepared-only delivery actions always serialize the current draft, never a host source. */
+declare function createTransferEmailActions(email: ContentTransferEmailPort, options?: {
+    jsonFormat?: FormatAdapter;
+}): TransferEmailAction[];
+
+interface AlchemyCopyVariant {
+    id: string;
+    label: string;
+    hint?: string;
+    icon?: React.ComponentType<{
+        className?: string;
+    }>;
+    section?: "copy" | "ai";
+    ariaLabel?: string;
+    successMessage?: string;
+    build?: () => AgentPayloadInput | string | Promise<AgentPayloadInput | string>;
+    onSelect?: () => void | Promise<void>;
+    modal?: (props: {
+        open: boolean;
+        onOpenChange: (open: boolean) => void;
+    }) => React.ReactNode;
+    /** Opens THE preparation workspace on this content (the rows tree for rows, PP-08). */
+    prepare?: () => {
+        payload: Payload;
+        label: string;
+        envelope?: EnvelopeMeta;
+    };
+}
+interface AlchemyExportItem {
+    id: string;
+    label: string;
+    build?: () => {
+        content: BlobPart;
+        extension: string;
+        mime: string;
+        /** Optional exact safe basename captured with bytes; omission derives a default, invalid values error. */
+        filename?: string;
+    };
+    onSelect?: () => void | Promise<void>;
+}
+type Resolvable<T> = T | (() => T);
+interface MatrxCopyMenuProps {
+    label: string;
+    /** Stable record identity when this mounted control can switch between records. */
+    sourceId?: string;
+    references?: readonly ContentTransferReference[];
+    referenceActions?: readonly ContentTransferReferenceAction[];
+    /** Prepare the tabular view while keeping raw JSON and human copy formats. */
+    primarySource?: "table";
+    human?: Resolvable<string>;
+    /**
+     * What `human` is. "markdown" makes it rich text: the main Copy click writes text/plain = the
+     * markdown plus text/html = formatted, and the panel leads with "Copy markdown" and "Copy text".
+     * Default "plain": a plain string, the existing Text / Markdown tiles.
+     */
+    contentFlavor?: "plain" | "markdown";
+    /**
+     * The host's own rich copy, so one implementation serves every surface (matrx-frontend injects
+     * `copyRichContent`). Absent: the package writes the main click and Copy markdown through the session
+     * transport and offers no Copy text tile (readable text is the host's one projection).
+     */
+    richCopy?: (markdown: string, flavor: RichCopyFlavor) => Promise<TransferOutcome | boolean | void> | TransferOutcome | boolean | void;
+    json?: Resolvable<unknown>;
+    agent?: Resolvable<AgentPayloadInput | string>;
+    aiVariants?: AlchemyCopyVariant[];
+    aiCustom?: AlchemyCustomSource;
+    groomer?: () => AlchemyGroomerConfig;
+    agentVariant?: {
+        id?: string;
+        label?: string;
+        hint?: string;
+        position?: "first" | "last";
+    };
+    export?: {
+        items: AlchemyExportItem[];
+        /** May be async: a server-paged host hands its whole selected result, read when a format is picked. */
+        sheetRows?: () => Array<Record<string, unknown>> | Promise<Array<Record<string, unknown>>>;
+        sheetColumns?: () => Array<{
+            id: string;
+            label: string;
+        }>;
+    };
+    /** Host-owned authenticated destination, not a second export serializer. */
+    sendToSheet?: (rows: Array<Record<string, unknown>>, label: string) => Promise<TransferOutcome>;
+    hide?: Array<"copy" | "ai" | "export">;
+    disabled?: boolean;
+    className?: string;
+    stopPropagation?: boolean;
+    size?: "xs" | "icon" | "sm" | "toolbar";
+    appearance?: "bare" | "segmented";
+    unified?: boolean;
+    grouped?: boolean;
+    icon?: AlchemyIcon;
+    triggerVariant?: "transparent" | "glass" | "outline";
+    /** The full controller, or the table's subset (`TableCopyController`, design-system's copy contract). */
+    controllerRef?: React.Ref<ContentTransferController> | React.Ref<TableCopyController>;
+    triggerHidden?: boolean;
+}
+/** Opinionated bridge for Matrx's existing content builders, with one transfer UI. */
+declare function MatrxCopyMenu(props: MatrxCopyMenuProps): React.JSX.Element;
+declare const GROOMER_LEVELS: AlchemyDetail[];
+declare function defaultGroomerSelections(sections: AlchemyGroomerSection[]): Record<string, AlchemyDetail | "off">;
+declare function buildGroomerPresetPayload(config: AlchemyGroomerConfig, preset: AlchemyGroomerPreset): AgentPayloadInput;
+declare function groomerPresetVariants(getConfig: () => AlchemyGroomerConfig): AlchemyCopyVariant[];
+
+/**
+ * THE table copy control (ALC-16): what a host binds as `MatrxDataTableHost.CopyControls`.
+ * design-system's table sits below alchemy, so it speaks only the copy contract
+ * (`CopyControlProps`); this answers it with the one Alchemy menu.
+ */
+declare function AlchemyTableCopyControls(props: CopyControlProps): React.JSX.Element;
+
+type ContentTransferReferenceAction = {
+    id: string;
+    label: string;
+    run(): void | Promise<void>;
+};
+declare function AlchemyGlyph({ icon, ...props }: React.SVGAttributes<SVGSVGElement> & {
+    icon?: AlchemyIcon;
+}): React.JSX.Element;
+/** What a host injects into the menu: lazy format adapters (`@ai-matrx/alchemy/operate`) and AI preparation. */
+type TransferCapabilities = {
+    formats?: FormatAdapter[];
+    ai?: AiPreparation;
+};
+type ContentTransferCapabilities = TransferCapabilities & {
+    /** Opaque host session boundary. It is used only to reset local menu state. */
+    identityKey?: string;
+    transport?: Transport;
+    reference?: ContentTransferReferencePort;
+    email?: ContentTransferEmailPort;
+    actions?: PageAction[];
+    preferences?: TransferPreferenceOverrides;
+    onOutcome?: (outcome: TransferOutcome) => void;
+    /**
+     * The host's window system (structurally `@ai-matrx/alchemy/ports` `WindowPort`, PP-01a). Bound:
+     * the preparation workspace opens inside a host window (WindowPanel in the web app, an honest
+     * full-screen dialog in the dashboard). Unbound: a near-full-screen dialog.
+     */
+    window?: WorkspaceWindowPort;
+};
+declare function ContentTransferCapabilitiesProvider({ value, children }: {
+    value: ContentTransferCapabilities;
+    children: React.ReactNode;
+}): React.JSX.Element;
+declare const useContentTransferCapabilities: () => ContentTransferCapabilities;
+declare function ContentTransferSurfaceProvider({ handle, children }: {
+    handle: SurfaceHandle;
+    children: React.ReactNode;
+}): React.JSX.Element;
+declare const useContentTransferSurface: () => SurfaceHandle | null;
+interface TransferMenuPresentation {
+    group?: "save" | "chat" | "email";
+    prepared?: boolean;
+    hint?: string;
+    icon?: React.ComponentType<{
+        className?: string;
+    }>;
+    ariaLabel?: string;
+    /**
+     * Download-only actions join the shared format palette instead of a second menu. A "prepare"
+     * action opens THE preparation workspace (the table's "Filter & sort before copying…" door) and
+     * sits in "Edit and prepare", where people look for it — never under a heading of its own.
+     */
+    placement?: "download" | "prepare";
+}
+/**
+ * THE PALETTE'S HEADINGS — a closed list. A host never supplies a heading: an action picks one of
+ * the named `group`s or its row shows INLINE with no heading (the approved-heading rule of
+ * `@ai-matrx/alchemy/menu`; a container word such as "Actions" or "More…" is never a heading).
+ */
+declare const PALETTE_HEADINGS: readonly ["Copy as", "Download as", "Quick copy", "Copy for AI", "Edit and prepare", "Other sources", "References", "Save to Matrx", "Continue with AI", "Email to me"];
+type PaletteHeading = (typeof PALETTE_HEADINGS)[number];
+interface TransferMenuVariant extends TransferMenuPresentation {
+    id: string;
+    label: string;
+    source: Source | Payload;
+    copyLabel?: string;
+    section?: "copy" | "ai";
+    successMessage?: string;
+}
+interface ContentTransferMenuProps {
+    source?: Payload | Source;
+    projection?: ExportProjection;
+    sections?: Section[];
+    preferences?: TransferPreferenceOverrides;
+    enabled?: boolean;
+    surface?: SurfaceHandle;
+    label?: string;
+    /**
+     * Tabular sources. `size` is the live size the host knows ("1,240 rows · 12 columns"): the
+     * palette's "Filter & sort before copying…" door shows it (PP-08).
+     */
+    table?: {
+        availableScopes: TransferScope[];
+        initialScope: TransferScope;
+        scopeLabels?: Partial<Record<TransferScope, string>>;
+        size?: string;
+    };
+    references?: readonly ContentTransferReference[];
+    referenceActions?: readonly ContentTransferReferenceAction[];
+    /** A quick format may explicitly capture a different representation. */
+    formatSources?: Partial<Record<SerializableFormat, Source | Payload>>;
+    /** Set false for action-only hosts; source formats and adapters are then omitted. */
+    sourceFormats?: boolean;
+    /** Named alternate sources open this same preparation workspace. */
+    variants?: readonly TransferMenuVariant[];
+    actions?: (PageAction & TransferMenuPresentation)[];
+    capabilities?: ContentTransferCapabilities;
+    disabled?: boolean;
+    /** Portal is the default Alchemy mark; copy-transform remains opt-in. */
+    icon?: AlchemyIcon;
+    /** Uses the canonical TapTargetButton presentation. */
+    triggerVariant?: "transparent" | "glass" | "outline";
+    triggerSize?: "default" | "compact";
+    /** Mount the transfer session without a visible trigger for a host-owned menu command. */
+    triggerHidden?: boolean;
+    className?: string;
+    stopPropagation?: boolean;
+    hide?: readonly ("copy" | "prepare" | "download")[];
+    controllerRef?: React.Ref<ContentTransferController>;
+    /** Who the primary source is, for the AI envelope (PP-10); read when the workspace opens. */
+    envelope?: () => EnvelopeMeta | undefined;
+    /**
+     * Rich-text hosts: one implementation of the three copies. The main Copy click runs "default"
+     * (text/plain = markdown AND text/html = formatted); the panel leads with "Copy markdown" and
+     * "Copy text". When set, the plain / Markdown tiles give way to those two.
+     */
+    richCopy?: RichCopyRunner;
+    /** The flavors the runner can honestly produce as tiles (default both). A host with no readable-text projection omits "text". */
+    richCopyFlavors?: readonly Exclude<RichCopyFlavor, "default">[];
+}
+type RichCopyFlavor = "default" | "markdown" | "text";
+type RichCopyRunner = (flavor: RichCopyFlavor) => Promise<TransferOutcome | boolean | void> | TransferOutcome | boolean | void;
+interface ContentTransferController {
+    focusTrigger(): void;
+    /** Mount the one canonical Alchemy palette in a host-owned menu surface. */
+    mountPalette(target: HTMLElement | null, onClose?: () => void, restoreFocus?: () => void): void;
+    preparePrimary(options?: {
+        restoreFocus?: () => void;
+    }): Promise<void>;
+    prepare(source: Source | Payload, options?: {
+        id?: string;
+        label?: string;
+        envelope?: EnvelopeMeta;
+    }): Promise<void>;
+    /** Open the workspace on a host's own levers (aiCustom / groomer): the levers live beside the preview (PP-02). */
+    prepareLevers(levers: WorkspaceLevers, options: {
+        id: string;
+        label: string;
+    }): Promise<void>;
+}
+declare function ContentTransferMenu(props: ContentTransferMenuProps): React.JSX.Element;
+/**
+ * What a source can say about itself without being built: its payload kind (and a text's language),
+ * and whether building it is cheap. The menu inspects a source that declares its shape by the shape
+ * alone, so opening the menu never builds the content — a person's pick does (sec_8f1a9be1…: a
+ * 1,636-organization page capture froze its page for 4.1 s on open). `cheap` sources (a short,
+ * already-built string) still take part in the twin check (PP-09); anything else is never built
+ * to decide which items to show.
+ */
+type SourceShape = {
+    kind: "text" | "markdown" | "json";
+    language?: string;
+    cheap?: boolean;
+};
+type ShapedSource = Source & {
+    shape?: SourceShape;
+};
+
+export { type AlchemyCopyVariant, type AlchemyCustomSource, type AlchemyDetail, type AlchemyExportItem, AlchemyGlyph, type AlchemyGroomerConfig, type AlchemyGroomerPreset, type AlchemyGroomerSection, type AlchemyOptionValues, type AlchemySourceOption, AlchemyTableCopyControls, type ContentTransferCapabilities, ContentTransferCapabilitiesProvider, type ContentTransferController, type ContentTransferEmailPort, ContentTransferMenu, type ContentTransferMenuProps, type ContentTransferReferenceAction, type ContentTransferReferencePort, ContentTransferSurfaceProvider, type EnvelopeMeta, GROOMER_LEVELS, MatrxCopyMenu, type MatrxCopyMenuProps, PALETTE_HEADINGS, type PaletteHeading, type RichCopyFlavor, type RichCopyRunner, type SerializableFormat, type ShapedSource, type SourceShape, type TransferCapabilities, type TransferMenuPresentation, type TransferMenuVariant, type WorkspaceLevers, type WorkspaceWindowHandle, type WorkspaceWindowPort, applyGroomerPreset, buildGroomerPresetPayload, createTransferEmailActions, defaultGroomerSelections, groomerPresetVariants, tableDataFormat, tableSchemaFormat, useContentTransferCapabilities, useContentTransferSurface };