@ai-matrx/kit 0.12.1 → 0.13.2

package/dist/content-transfer.d.ts

@@ -0,0 +1,356 @@
+/** Framework-neutral transfer contracts. All data crossing this boundary is JSON. */
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+type Payload = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "markdown";
+    text: string;
+} | {
+    kind: "json";
+    value: Json;
+} | {
+    kind: "rows";
+    rows: Record<string, Json>[];
+    columns: Column[];
+} | {
+    kind: "registered";
+    format: string;
+    value: Json;
+};
+type Column = {
+    id: string;
+    label: string;
+    path: string;
+    visible: boolean;
+    exportable?: boolean;
+    classification?: "ordinary" | "secret" | "credential";
+};
+type ExportProjection = {
+    rules: {
+        target: "payload" | "row";
+        path: string;
+        exportable: boolean;
+        classification: "ordinary" | "secret" | "credential";
+    }[];
+};
+type TransferScope = "target" | "row" | "selected" | "view" | "loaded" | "all-matching";
+type Section = {
+    id: string;
+    label: string;
+    path: string;
+    includedByDefault: boolean;
+};
+type Coverage = {
+    status: "complete" | "loaded" | "partial" | "unknown";
+    included: number;
+    total: number | null;
+    reason?: string;
+};
+type Omission = {
+    path: string;
+    reason: "excluded" | "filtered" | "truncated" | "unsupported" | "escaped" | "duplicate";
+    count?: number;
+};
+type RawSnapshot = {
+    id: string;
+    sourceId: string;
+    revision: string;
+    capturedAt: string;
+    label: string;
+    payload: Payload;
+    coverage: Coverage;
+    unsavedChanges: boolean;
+    omissions: Omission[];
+    sections: Section[];
+    limits?: TransferLimits;
+};
+declare const projected: unique symbol;
+type Snapshot = RawSnapshot & {
+    readonly [projected]: true;
+};
+type QuerySnapshot = {
+    sourceId: string;
+    revision: string;
+    query: Json;
+    order: {
+        field: string;
+        direction: "asc" | "desc";
+    }[];
+};
+type ExportPage = {
+    rows: Record<string, Json>[];
+    nextCursor: string | null;
+    coverage: Coverage;
+    consistencyToken: string | null;
+};
+type CapturedAllMatching = {
+    query: QuerySnapshot;
+    getRowId(row: Record<string, Json>): string;
+    page(request: {
+        query: QuerySnapshot;
+        cursor: string | null;
+        consistencyToken: string | null;
+        signal: AbortSignal;
+    }): Promise<ExportPage>;
+    stableSnapshot?: boolean;
+};
+type CapturedSource = {
+    snapshot: RawSnapshot;
+    projection: ExportProjection;
+    allMatching?: CapturedAllMatching;
+};
+type Source = {
+    id: string;
+    label: string;
+    capture(request: {
+        scope: TransferScope;
+        signal: AbortSignal;
+    }): Promise<CapturedSource>;
+};
+type Draft = {
+    snapshotId: string;
+    sourceId: string;
+    sourceRevision: string;
+    revision: number;
+    payload: Payload;
+    omissions: Omission[];
+    manuallyEdited: boolean;
+    provenance: {
+        kind: "original" | "deterministic" | "manual" | "ai";
+        operationId?: string;
+        description: string;
+    }[];
+    /** Frozen prior states, with history omitted to avoid recursive duplication. */
+    history?: readonly Omit<Draft, "history">[];
+};
+type Transform = {
+    id: string;
+    apply(draft: Draft, options: Json, signal: AbortSignal): Promise<Draft>;
+};
+type Artifact = {
+    snapshotId: string;
+    draftRevision: number;
+    format: string;
+    plainText: string;
+    html?: string;
+    file?: {
+        filename: string;
+        mime: string;
+        bytes: Uint8Array;
+    };
+    omissions: Omission[];
+};
+type FormatAdapter = {
+    id: string;
+    label: string;
+    supports(payload: Payload): boolean;
+    build(draft: Draft, signal: AbortSignal): Promise<Artifact>;
+};
+type TransferOutcome = {
+    status: "success";
+    delivered: "clipboard" | "download-started" | "action";
+    mimeTypes: string[];
+    /** Host-provided completion text for an explicit page action. */
+    message?: string;
+} | {
+    status: "degraded";
+    delivered: "plain-text";
+    reason: string;
+} | {
+    status: "cancelled";
+} | {
+    status: "error";
+    code: string;
+    message: string;
+    retryable: boolean;
+};
+type Transport = {
+    copy(artifact: Artifact, signal: AbortSignal): Promise<TransferOutcome>;
+    download(artifact: Artifact, signal: AbortSignal): Promise<TransferOutcome>;
+};
+type SurfaceHandle = {
+    instanceId: string;
+    surfaceName: string;
+    isMounted(): boolean;
+    capture(signal: AbortSignal): Promise<CapturedSource>;
+};
+type AiPreparation = {
+    supports(snapshot: Snapshot): boolean;
+    run(request: {
+        snapshot: Snapshot;
+        draft: Draft;
+        instruction: string;
+        signal: AbortSignal;
+    }): Promise<Draft>;
+    /** Create an isolated adapter session for one preparation workspace. */
+    fork?(): AiPreparation;
+    /** Cancel the retained provider request; closing a host UI does not imply this. */
+    cancel?(): Promise<void>;
+    /** Revalidate the frozen source and recover a previously saved provider result. */
+    recover?(input: {
+        snapshot: Snapshot;
+        draft: Draft;
+        signal: AbortSignal;
+    }): Promise<Draft>;
+};
+type TransferLimits = {
+    maxRows: number | null;
+    maxStringChars: number | null;
+    maxDepth: number | null;
+    maxArrayItems?: number | null;
+    targetTokens: number | null;
+};
+type TransferPreferences = {
+    initialFormat: string;
+    initialPreset: "full" | "compact" | "brief";
+    limits: TransferLimits;
+};
+type PageAction = {
+    /** Alternate click-time source, captured through the same projection and limits before run. */
+    source?: Source;
+    id: string;
+    label: string;
+    supports(snapshot: Snapshot): boolean;
+    run(request: {
+        snapshot: Snapshot;
+        draft: Draft;
+        signal: AbortSignal;
+    }): Promise<TransferOutcome>;
+};
+type TransferCapabilities = {
+    formats?: FormatAdapter[];
+    ai?: AiPreparation;
+};
+
+/** Matrx's portable, source-labelled envelope for external AI tools. */
+interface AgentPayloadInput {
+    kind: string;
+    location: string;
+    description: string;
+    data: unknown;
+    summary?: string;
+    attributes?: Record<string, string | number | boolean | null | undefined>;
+    context?: Record<string, string | number | boolean | null | undefined>;
+}
+interface AgentPayloadEnvironment {
+    url?: string;
+    route?: string;
+    capturedAt?: string;
+}
+/** A fence longer than any content fence prevents accidental Markdown closure. */
+declare function fenceJsonBlock(json: string): string;
+/** Capture location at invocation; environment injection makes non-browser use explicit. */
+declare function buildAgentPayload(input: AgentPayloadInput, environment?: AgentPayloadEnvironment): string;
+
+declare class ContentTransferError extends Error {
+    readonly code: string;
+    readonly path: string | undefined;
+    constructor(code: string, message: string, path?: string);
+}
+declare const bound: unique symbol;
+type BoundAllMatching = {
+    readonly [bound]: true;
+    readonly source: CapturedAllMatching;
+    readonly projection: ExportProjection;
+    readonly columns: readonly Column[];
+    readonly limits?: TransferLimits;
+};
+/**
+ * Validates arbitrary host data at the transfer boundary and returns a detached
+ * JSON value.  This deliberately shares the capture validator: undefined,
+ * functions, dates, non-finite numbers, and cycles are rejected rather than
+ * silently coerced by a JSON stringify round trip.
+ */
+declare function normalizeTransferJson(value: unknown): Json;
+/** Column ids are identities, never an alternative data address. */
+declare function readTransferCell(row: Record<string, Json>, column: Column): Json | undefined;
+declare function projectSnapshot(raw: RawSnapshot, projection: ExportProjection): Snapshot;
+declare function directSource(payload: Payload, options?: Partial<Pick<RawSnapshot, "id" | "sourceId" | "revision" | "label" | "coverage" | "unsavedChanges" | "sections" | "limits"> & {
+    projection: ExportProjection;
+}>): CapturedSource;
+declare function capture(source: Source | Payload, signal: AbortSignal, scope?: TransferScope): Promise<{
+    snapshot: Snapshot;
+    allMatching?: BoundAllMatching;
+}>;
+declare function createDraft(s: Snapshot): Draft;
+declare const editDraft: (d: Draft, p: Payload) => Draft;
+declare const resetDraft: (s: Snapshot) => Draft;
+declare const sourceChanged: (d: Draft, s: Snapshot) => boolean;
+declare function undoDraft(d: Draft): Draft;
+/** Keep and regenerate are explicit choices; observing fresh data never overwrites edits. */
+declare function refreshDraft(draft: Draft, snapshot: Snapshot, choice: "keep" | "regenerate"): Draft;
+declare function applySectionSelection(d: Draft, s: Snapshot, ids: readonly string[]): Draft;
+declare function transformRows(d: Draft, o: {
+    search?: string;
+    sort?: {
+        column: string;
+        direction: "asc" | "desc";
+    };
+    filters?: Readonly<Record<string, string>>;
+    /** Positions in this call's input draft rows; unlike ids, no guessed key is used. */
+    selectedIndices?: readonly number[];
+    selectedIds?: readonly string[];
+    idColumn?: string;
+    visibleColumns?: readonly string[];
+    structuredProjection?: "full" | "visible";
+    top?: number | null;
+}): Draft;
+declare function reduceJson(draft: Draft, options: {
+    exclude?: readonly string[];
+    maxDepth?: number | null;
+    maxStringChars?: number | null;
+    maxArrayItems?: number | null;
+}): Draft;
+declare function collectAllMatching(c: BoundAllMatching, signal: AbortSignal): Promise<{
+    rows: Record<string, Json>[];
+    coverage: RawSnapshot["coverage"];
+    omissions: Omission[];
+    error?: ContentTransferError;
+}>;
+/** Preserve artifact-byte identity even if a consumer mutates a returned view. */
+declare function sealTransferArtifact(artifact: Artifact): Artifact;
+declare function serialize(draft: Draft, format: "plain" | "markdown" | "json" | "compact-json" | "csv" | "tsv" | "html", options?: {
+    spreadsheetSafe?: boolean;
+    filename?: string;
+}): Artifact;
+declare function renderMarkdownHtml(markdown: string): Promise<string>;
+declare function serializeMarkdownRich(d: Draft, filename?: string): Promise<Artifact>;
+declare function createBrowserTransport(): Transport;
+type TransferPreferenceOverrides = Partial<Omit<TransferPreferences, "limits">> & {
+    limits?: Partial<TransferLimits>;
+};
+/** Restrictions intersect: neither a menu nor a provider can relax a source limit. */
+declare function resolveTransferPreferences(provider?: TransferPreferenceOverrides, menu?: TransferPreferenceOverrides, sourceLimits?: Partial<TransferLimits>): TransferPreferences;
+/** One stable id per registered format or action; ambiguous overrides fail loudly. */
+declare function resolveTransferRegistry<T extends {
+    id: string;
+}>(...groups: readonly (readonly T[])[]): readonly T[];
+type TransferSurfaceDeclaration = {
+    surfaceName: string;
+    label?: string;
+    values: readonly {
+        name: string;
+        label: string;
+        exportable?: boolean;
+        classification?: "ordinary" | "secret" | "credential";
+        includedByDefault?: boolean;
+    }[];
+};
+/** A structural adapter to the actual mounted surface, never a global name lookup. */
+declare function createSurfaceTransferHandle(options: {
+    instanceId: string;
+    manifest: TransferSurfaceDeclaration;
+    isMounted(): boolean;
+    getScope(): Record<string, unknown> | Promise<Record<string, unknown>>;
+    getRevision?(): string;
+    unsavedChanges?(): boolean;
+    projection?: ExportProjection;
+    limits?: TransferLimits;
+}): SurfaceHandle;
+/** Applies explicit preparation/source limits with exact omissions; token target is advisory. */
+declare function applyTransferLimits(draft: Draft, limits: Partial<TransferLimits>): Draft;
+
+export { type AgentPayloadEnvironment, type AgentPayloadInput, type AiPreparation, type Artifact, type BoundAllMatching, type CapturedAllMatching, type CapturedSource, type Column, ContentTransferError, type Coverage, type Draft, type ExportPage, type ExportProjection, type FormatAdapter, type Json, type Omission, type PageAction, type Payload, type QuerySnapshot, type RawSnapshot, type Section, type Snapshot, type Source, type SurfaceHandle, type TransferCapabilities, type TransferLimits, type TransferOutcome, type TransferPreferenceOverrides, type TransferPreferences, type TransferScope, type TransferSurfaceDeclaration, type Transform, type Transport, applySectionSelection, applyTransferLimits, buildAgentPayload, capture, collectAllMatching, createBrowserTransport, createDraft, createSurfaceTransferHandle, directSource, editDraft, fenceJsonBlock, normalizeTransferJson, projectSnapshot, readTransferCell, reduceJson, refreshDraft, renderMarkdownHtml, resetDraft, resolveTransferPreferences, resolveTransferRegistry, sealTransferArtifact, serialize, serializeMarkdownRich, sourceChanged, transformRows, undoDraft };