/** Host artifact kinds accepted by launch delivery and artifact resolution. */
declare type MiniAppArtifactKind = 'channel-message' | 'pull-request' | 'task' | 'repository-issue';

/**
 * An immutable, host-minted reference to a host artifact. A host invocation
 * receives this reference plus launch context — never copied content — and
 * packages resolve it through
 * {@link MiniAppArtifactsApi.resolve} under the package's permissions.
 */
declare type MiniAppArtifactReference = {
    /** Opaque host authority handle; artifact coordinates alone are not resolvable. */
    readonly referenceId: string;
    readonly kind: MiniAppArtifactKind;
    readonly artifactId: string;
    readonly workspaceId: string;
    readonly mintedAt: number;
    readonly expiresAt: number;
};

/**
 * Opaque, host-issued authority to one user-selected file.
 *
 * Handles deliberately contain no native path. The revision is the snapshot
 * observed when the handle was issued, refreshed by `metadata` or `watch`, or
 * returned after a mutation. Callers may also pass a newer observed revision
 * as a mutation fence without modifying the handle. `recoverable` tells callers
 * whether `recover` may restore the handle in a later desktop session.
 */
declare type MiniAppFileHandle = Readonly<Omit<MiniappUserFileHandle, 'expiresAt'> & {
    expiresAt: number | null;
}>;

/** JSON-compatible values accepted by public miniapp operations. */
declare type MiniAppJsonValue = null | boolean | number | string | MiniAppJsonValue[] | {
    [key: string]: MiniAppJsonValue;
};

declare type MiniappUserFileHandle = {
    id: string;
    revision: string;
    recoverable: boolean;
    expiresAt?: string | undefined;
};

/**
 * Mount a converted VS Code webview while retaining all TAP authority in the
 * outer federated surface. The imported page receives only the explicitly
 * configured compatibility operations.
 */
export declare function mountVsCodeWebview(container: HTMLElement, context: TapFederatedSurfaceMountContext, options: TapVsCodeWebviewBridgeOptions): TapVsCodeWebviewMount;

/**
 * Host-owned entropy for release-scoped identifiers.
 *
 * Ordinary TAP surfaces use the browser's cryptographically strong UUID
 * source. Test Lab mounts derive a deterministic stream from the selected
 * profile seed and exact frame identity, then reset it before each mount so
 * app-owned state is reproducible without weakening production identifiers,
 * colliding across retained remounts, or relying on ambient test globals.
 */
declare interface TapFederatedSurfaceEntropy {
    randomUUID(): string;
}

/**
 * Read-only authority projected by TAP for the exact package release/frame.
 * A candidate frame starts without authority and may only perform host-backed
 * work after the host confirms that release. Subscribers are notified only
 * when the boolean snapshot changes.
 */
declare interface TapFederatedSurfaceHostAuthority {
    getSnapshot(): boolean;
    subscribe(listener: () => void): () => void;
}

/** One verified host invocation routed to this exact surface realm. */
declare interface TapFederatedSurfaceLaunch {
    readonly requestId: string;
    readonly actionContributionId: string;
    readonly invokedAt: number;
    readonly reference: MiniAppArtifactReference;
    readonly owner?: TapFederatedSurfaceLaunchOwnerContext;
}

/**
 * Ordered, at-least-once context-action delivery.
 *
 * The runtime acknowledges a launch only after one listener returns `true`.
 * Consumers must use `requestId` as the idempotency key for durable effects.
 */
declare interface TapFederatedSurfaceLaunches {
    subscribe(listener: (launch: TapFederatedSurfaceLaunch) => boolean | Promise<boolean>): () => void;
}

/** Bounded host ownership snapshot attached to one immutable launch. */
declare interface TapFederatedSurfaceLaunchOwnerContext {
    readonly workspaceId: string;
    readonly channelId: string | null;
    readonly conversationId: string | null;
}

/** Cleanup handle returned by a federated surface mount. */
declare interface TapFederatedSurfaceMount {
    unmount(): void | Promise<void>;
}

/** Context supplied by TAP's isolated webview surface runtime. */
declare interface TapFederatedSurfaceMountContext {
    readonly packageId: string;
    readonly packageNamespace: string;
    readonly releaseId: string;
    readonly installationId: string;
    readonly contributionId: string;
    readonly instanceId: string;
    readonly hostOrigin: string;
    readonly packageAssetBaseUrl: string;
    /**
     * Host-canonical control-plane user identity for this interactive mount.
     *
     * This is intentionally distinct from an OAuth/OIDC profile subject. It is
     * the same user identity used when resolving MCP `{userId}` storage reads.
     * Activation preflight mounts do not receive user state and may omit it.
     */
    readonly userId?: string;
    readonly workspaceId?: string;
    readonly channelId?: string;
    readonly conversationId?: string;
    /**
     * One host-validated file-handler invocation for this mount. Later OS
     * launches create a fresh mount; they are never delivered over an event or
     * ambient subscription.
     */
    readonly userFileLaunchContext?: TapFederatedSurfaceUserFileLaunchContext;
    readonly events: TapPackageEventPublisher;
    readonly entropy: TapFederatedSurfaceEntropy;
    readonly hostAuthority: TapFederatedSurfaceHostAuthority;
    readonly owner: TapFederatedSurfaceOwner;
    readonly launches: TapFederatedSurfaceLaunches;
}

/**
 * Live host-selected owner for broad retained realms.
 *
 * The snapshot starts as `null` until the host projects an owner. Consumers
 * must subscribe when their behavior depends on channel or conversation
 * selection because `per-workspace` and `singleton` realms can change owners
 * without remounting.
 */
declare interface TapFederatedSurfaceOwner {
    getSnapshot(): TapFederatedSurfaceOwnerSnapshot | null;
    subscribe(listener: () => void): () => void;
}

/**
 * Host-selected owner of one retained surface realm.
 *
 * These fields describe the current UI owner, not the immutable instance
 * policy scope exposed directly on `TapFederatedSurfaceMountContext`.
 */
declare interface TapFederatedSurfaceOwnerSnapshot {
    readonly workspaceId: string | null;
    readonly channelId: string | null;
    readonly conversationId: string | null;
}

/** Initial file-handler invocation delivered only with a Surface mount. */
declare type TapFederatedSurfaceUserFileLaunchContext = Readonly<{
    apiVersion: 1;
    intent: 'open' | 'import' | 'export';
    handle: MiniAppFileHandle;
}>;

/** Declared package-event channel supplied to an isolated UI contribution. */
declare interface TapPackageEventPublisher {
    publish(name: string, payload: Readonly<Record<string, unknown>>): void | Promise<void>;
    subscribe(name: string, listener: (payload: unknown, envelope: Readonly<Record<string, unknown>>) => void | Promise<void>): () => void;
}

export declare interface TapVsCodeWebviewBootstrapBinding {
    /** Path to read in the stored JSON value. */
    statePath: readonly string[];
    /** Path to update in the bootstrap JSON value. */
    bootstrapPath: readonly string[];
    transform?: Exclude<TapVsCodeWebviewValueTransform, 'byte-array-to-base64'>;
}

export declare interface TapVsCodeWebviewBootstrapOptions {
    selector: string;
    attribute: string;
    encoding: 'base64-json';
    value: MiniAppJsonValue;
}

export declare interface TapVsCodeWebviewBridgeOptions {
    title: string;
    entryPath: string;
    /** Browser runtime emitted from `tapVsCodeWebviewRuntimeSource`. */
    runtimePath: string;
    bootstrap?: TapVsCodeWebviewBootstrapOptions;
    storage?: TapVsCodeWebviewStorageOptions;
    session?: TapVsCodeWebviewSessionOptions;
    network?: TapVsCodeWebviewNetworkOptions;
    onMessage?: (message: unknown) => void | Promise<void>;
    /**
     * An async handler is accepted and its rejection is reported like a
     * synchronous throw, never left unhandled. The return type stays exactly
     * `void` rather than `void | Promise<void>`: TypeScript only ignores a
     * callback's returned value when the expected return type is precisely
     * `void`, so widening it to a union would reject an ordinary handler like
     * `(error) => errors.push(error)`.
     */
    onError?: (error: Error) => void;
}

export declare interface TapVsCodeWebviewMessageBinding {
    /** Exact value of the message discriminator (normally `message.type`). */
    messageType: string;
    /** Path to the value in the webview message. */
    messageValuePath: readonly string[];
    /** Path to update in the JSON value stored by `sdk.storage`. */
    statePath: readonly string[];
    transform?: Exclude<TapVsCodeWebviewValueTransform, 'base64-to-byte-array'>;
}

export declare interface TapVsCodeWebviewMount extends TapFederatedSurfaceMount {
    postMessage(message: unknown): void;
}

export declare interface TapVsCodeWebviewNetworkOptions {
    /** Exact HTTPS origins approved by the conversion recipe. */
    allowedOrigins: readonly string[];
}

/**
 * Self-contained browser runtime written next to a converted webview by the
 * conversion CLI. Keeping this byte string in the SDK prevents generated
 * adapters from growing a second, incompatible bridge implementation.
 */
export declare const tapVsCodeWebviewRuntimeSource: string;

export declare interface TapVsCodeWebviewSessionOptions {
    /**
     * Field inside the installation-scoped `sdk.session` object. The iframe gets
     * a synchronous in-memory localStorage facade backed by this field.
     */
    namespace: string;
}

export declare interface TapVsCodeWebviewStorageOptions {
    namespace: string;
    key: string;
    initialValue: MiniAppJsonValue;
    messageTypePath?: readonly string[];
    messageBindings?: readonly TapVsCodeWebviewMessageBinding[];
    bootstrapBindings?: readonly TapVsCodeWebviewBootstrapBinding[];
    /**
     * Optional path used for the synchronous `acquireVsCodeApi().getState()` and
     * `setState()` compatibility value.
     */
    vscodeStatePath?: readonly string[];
}

export declare type TapVsCodeWebviewValueTransform = 'identity' | 'byte-array-to-base64' | 'base64-to-byte-array';

export { }