Plugin Artifact API.

export declare function isValidationError(error: unknown): error is PluginArtifactValidationError;

/**
 * Parses and compatibility-gates schema-1 `plugin.json` without touching code.
 */
export declare function parsePluginManifest(source: string | Uint8Array, context: PluginCompatibilityContext): PluginManifest;

/**
 * Validates one explicit artifact directory without discovery or code
 * execution. Failures throw `PluginArtifactValidationError`.
 */
export declare function validatePluginArtifact(directory: string, options: PluginArtifactValidationOptions): Promise<ValidatedPluginArtifact>;

/** Result-shaped companion for UI and batch discovery callers. */
export declare function validatePluginArtifactResult(directory: string, options: PluginArtifactValidationOptions): Promise<PluginArtifactValidationResult>;

/**
 * Reconciles untrusted persisted values with the current manifest schema.
 * Unknown and invalid values are reported and omitted; declared defaults are
 * copied into the effective view.
 */
export declare function validatePluginSettings(manifest: PluginManifest, stored: unknown): ValidatedPluginSettings;

export declare function validPluginSettingValue(declaration: PluginSettingDeclaration, value: unknown): value is PluginSettingValue;

/**
 * Process-local content-addressed cache for the future app-owned protocol.
 *
 * Entries contain copies of validated bytes. Serving code asks by digest and
 * never receives or reopens the original filesystem path.
 */
export declare class PluginArtifactCache {
    private readonly modules;
    get size(): number;
    has(digest: string): boolean;
    get(digest: string): ValidatedPluginModule | null;
    keys(): IterableIterator<string>;
    retain(module: ValidatedPluginModule): ValidatedPluginModule;
    delete(digest: string): boolean;
    clear(): void;
}

/** Typed validation failure suitable for both logs and compatibility UI. */
export declare class PluginArtifactValidationError extends Error {
    readonly diagnostic: PluginArtifactDiagnostic;
    constructor(diagnostic: PluginArtifactDiagnostic, options?: ErrorOptions);
}

export interface PluginArtifactDiagnostic {
    readonly category: PluginArtifactDiagnosticCategory;
    readonly code: PluginArtifactDiagnosticCode;
    readonly message: string;
    readonly path?: string;
    readonly pluginId?: string;
}

export type PluginArtifactDiagnosticCategory = 'missing' | 'malformed' | 'incompatible' | 'unsupported' | 'corrupt';

export type PluginArtifactDiagnosticCode = 'ARTIFACT_NOT_FOUND' | 'ARTIFACT_NOT_DIRECTORY' | 'ARTIFACT_UNREADABLE' | 'ARTIFACT_FILES_UNSUPPORTED' | 'MANIFEST_MISSING' | 'MANIFEST_NOT_REGULAR' | 'MANIFEST_TOO_LARGE' | 'MANIFEST_INVALID_UTF8' | 'MANIFEST_INVALID_JSON' | 'MANIFEST_INVALID_SHAPE' | 'MANIFEST_FIELD_INVALID' | 'MANIFEST_KEY_UNSUPPORTED' | 'MANIFEST_SCHEMA_UNSUPPORTED' | 'APP_INCOMPATIBLE' | 'SDK_INCOMPATIBLE' | 'CAPABILITY_UNSUPPORTED' | 'ENTRY_MISSING' | 'ENTRY_PATH_INVALID' | 'ENTRY_ESCAPES_ARTIFACT' | 'ENTRY_NOT_REGULAR' | 'ENTRY_TOO_LARGE' | 'ENTRY_INVALID_UTF8' | 'ENTRY_DIGEST_MISMATCH' | 'ENTRY_SYNTAX_INVALID' | 'ENTRY_IMPORT_UNSUPPORTED' | 'ENTRY_SOURCE_MAP_UNSUPPORTED' | 'ICON_PATH_INVALID' | 'ICON_NOT_REGULAR' | 'ICON_TOO_LARGE' | 'ICON_COUNT_EXCEEDED' | 'ICON_INVALID_UTF8' | 'ICON_SVG_INVALID';

export interface PluginArtifactValidationOptions extends PluginCompatibilityContext {
    /** Optional shared content-addressed retention for the future protocol. */
    readonly cache?: PluginArtifactCacheLike;
}

export type PluginArtifactValidationResult = {
    readonly ok: true;
    readonly value: ValidatedPluginArtifact;
} | {
    readonly ok: false;
    readonly diagnostic: PluginArtifactDiagnostic;
};

export type PluginCapability = (typeof PLUGIN_CAPABILITIES)[number];

export interface PluginCompatibilityContext {
    /** Stable host application SemVer. */
    readonly appVersion: string;
    /** Exact public SDK package/contract version accepted by this host. */
    readonly sdkVersion: string;
}

export type PluginManifest = PluginManifestV1 | PluginManifestV2;

export interface PluginManifestV1 extends PluginManifestBase {
    readonly schemaVersion: 1;
    readonly capabilities: readonly [
        'node-kinds'
    ];
}

export interface PluginManifestV2 extends PluginManifestBase {
    readonly schemaVersion: 2;
    readonly capabilities: readonly PluginCapability[];
    readonly network: readonly PluginNetworkDeclaration[];
    readonly remoteMedia: readonly PluginRemoteMediaDeclaration[];
    readonly settings: readonly PluginSettingDeclaration[];
    readonly secrets: readonly PluginSecretDeclaration[];
}

export interface PluginNetworkDeclaration {
    readonly origin: string;
    readonly methods: readonly PluginNetworkMethod[];
    readonly purpose: string;
}

export type PluginNetworkMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';

export interface PluginRemoteMediaDeclaration {
    readonly origin: string;
    readonly mediaTypes: readonly PluginRemoteMediaType[];
    readonly purpose: string;
}

export type PluginRemoteMediaType = 'image/avif' | 'image/gif' | 'image/jpeg' | 'image/png' | 'image/webp';

export interface PluginSecretDeclaration {
    readonly name: string;
    readonly label: string;
    readonly description: string;
    readonly required: boolean;
}

export type PluginSettingDeclaration = (PluginSettingDeclarationBase & {
    readonly type: 'string';
    readonly default?: string;
}) | (PluginSettingDeclarationBase & {
    readonly type: 'number';
    readonly default?: number;
}) | (PluginSettingDeclarationBase & {
    readonly type: 'boolean';
    readonly default?: boolean;
}) | (PluginSettingDeclarationBase & {
    readonly type: 'enum';
    readonly values: readonly string[];
    readonly default?: string;
}) | (PluginSettingDeclarationBase & {
    readonly type: 'secret-ref';
    readonly secret: string;
});

export type PluginSettingValue = string | number | boolean;

export interface ValidatedPluginArtifact {
    /** Canonical path used only for diagnostics and discovery identity. */
    readonly directory: string;
    /** SHA-256 of the exact bounded plugin.json bytes accepted by validation. */
    readonly manifestDigest: string;
    readonly manifest: PluginManifest;
    readonly module: ValidatedPluginModule;
    readonly icons: readonly ValidatedPluginIcon[];
}

/** Immutable, validated SVG toolbar asset bundled beside the plugin entry. */
export interface ValidatedPluginIcon {
    /** Explicit plugin-relative path, for example `./icons/search.svg`. */
    readonly path: string;
    readonly digest: string;
    readonly source: string;
    readonly byteLength: number;
}

/**
 * Immutable content retained after validation.
 *
 * `readBytes` returns a copy so callers cannot mutate what a later protocol
 * response serves. No API exposes a source path that should be read again.
 */
export interface ValidatedPluginModule {
    readonly digest: string;
    readonly byteLength: number;
    readonly source: string;
    readBytes(): Uint8Array;
}

export interface ValidatedPluginSettings {
    readonly values: Readonly<Record<string, PluginSettingValue>>;
    readonly invalidKeys: readonly string[];
    readonly removedKeys: readonly string[];
}

export declare const MAX_PLUGIN_BUNDLE_BYTES: number;

export declare const MAX_PLUGIN_ICON_BYTES: number;

export declare const MAX_PLUGIN_ICON_COUNT = 16;

export declare const MAX_PLUGIN_ICON_TOTAL_BYTES: number;

export declare const MAX_PLUGIN_MANIFEST_BYTES: number;

export declare const PLUGIN_CAPABILITIES: readonly [
    "node-kinds",
    "commands",
    "editor-ui",
    "importers",
    "network",
    "configuration",
    "secrets",
    "remote-media",
    "interaction-regions",
    "agent-actions"
];

export declare const PLUGIN_ENTRY_FILE = "plugin.mjs";

export declare const PLUGIN_MANIFEST_FILE = "plugin.json";

export declare const PLUGIN_MANIFEST_SCHEMA_VERSION = 2;

export declare const SUPPORTED_PLUGIN_MANIFEST_SCHEMA_VERSIONS: readonly [
    1,
    2
];