@epicdm/flowstate-extension-core 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,1972 @@
+/**
+ * Comprehensive TypeScript types for VS Code extension package.json manifests.
+ *
+ * Covers the full VS Code Extension Manifest specification including all stable
+ * (GA) contribution points. Based on the VS Code Extension API documentation.
+ *
+ * @see https://code.visualstudio.com/api/references/extension-manifest
+ * @see https://code.visualstudio.com/api/references/contribution-points
+ */
+/**
+ * A string that may be localized. When localized, it uses the `%key%` syntax
+ * in the manifest, resolving to a value in the `package.nls.json` file.
+ * In the resolved form it can be either a plain string or a structured object
+ * with both the localized value and the original key.
+ */
+type LocalizedString = string | {
+    value: string;
+    original: string;
+};
+/**
+ * Icon definition supporting light/dark theme variants.
+ */
+interface IconDefinition {
+    light: string;
+    dark: string;
+}
+/**
+ * Icon reference — either a single path string or a light/dark pair.
+ */
+type IconReference = string | IconDefinition;
+/**
+ * Valid extension categories in the VS Code marketplace.
+ */
+type ExtensionCategory = 'Azure' | 'Data Science' | 'Debuggers' | 'Education' | 'Extension Packs' | 'Formatters' | 'Keymaps' | 'Language Packs' | 'Linters' | 'Machine Learning' | 'Notebooks' | 'Other' | 'Programming Languages' | 'SCM Providers' | 'Snippets' | 'Testing' | 'Themes' | 'Visualization';
+/**
+ * Where an extension should run.
+ * - `'ui'` — runs in the local (UI) extension host
+ * - `'workspace'` — runs in the remote workspace extension host
+ */
+type ExtensionKind = 'ui' | 'workspace';
+/**
+ * Declares how an extension behaves in untrusted workspaces.
+ */
+interface UntrustedWorkspaceCapability {
+    supported: boolean | 'limited';
+    description?: string;
+    restrictedConfigurations?: string[];
+}
+/**
+ * Declares how an extension behaves in virtual workspaces.
+ */
+interface VirtualWorkspaceCapability {
+    supported: boolean | 'limited';
+    description?: string;
+}
+/**
+ * Extension capabilities declaration.
+ */
+interface ExtensionCapabilities {
+    untrustedWorkspaces?: UntrustedWorkspaceCapability;
+    virtualWorkspaces?: VirtualWorkspaceCapability | boolean;
+}
+/**
+ * A badge to display on the marketplace page.
+ */
+interface Badge {
+    url: string;
+    href: string;
+    description: string;
+}
+/**
+ * Repository reference in package.json format.
+ */
+type RepositoryReference = string | {
+    type: string;
+    url: string;
+    directory?: string;
+};
+/**
+ * Bugs reference in package.json format.
+ */
+type BugsReference = string | {
+    url?: string;
+    email?: string;
+};
+/**
+ * A command contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.commands
+ */
+interface CommandContribution {
+    command: string;
+    title: LocalizedString;
+    category?: LocalizedString;
+    icon?: IconReference;
+    enablement?: string;
+    shortTitle?: LocalizedString;
+}
+/**
+ * A menu item contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.menus
+ */
+interface MenuContribution {
+    command?: string;
+    submenu?: string;
+    alt?: string;
+    when?: string;
+    group?: string;
+}
+/**
+ * A submenu contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.submenus
+ */
+interface SubmenuContribution {
+    id: string;
+    label: LocalizedString;
+    icon?: IconReference;
+}
+/**
+ * A keyboard shortcut contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.keybindings
+ */
+interface KeybindingContribution {
+    command: string;
+    key?: string;
+    when?: string;
+    mac?: string;
+    linux?: string;
+    win?: string;
+    args?: unknown;
+}
+/**
+ * Language icon definition.
+ */
+interface LanguageIcon {
+    light: string;
+    dark: string;
+}
+/**
+ * A language contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.languages
+ */
+interface LanguageContribution {
+    id: string;
+    extensions?: string[];
+    filenames?: string[];
+    filenamePatterns?: string[];
+    firstLine?: string;
+    aliases?: string[];
+    mimetypes?: string[];
+    configuration?: string;
+    icon?: LanguageIcon;
+}
+/**
+ * A TextMate grammar contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.grammars
+ */
+interface GrammarContribution {
+    language?: string;
+    scopeName: string;
+    path: string;
+    embeddedLanguages?: Record<string, string>;
+    tokenTypes?: Record<string, string>;
+    balancedBracketScopes?: string[];
+    unbalancedBracketScopes?: string[];
+    injectTo?: string[];
+}
+/**
+ * A snippet contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.snippets
+ */
+interface SnippetContribution {
+    language?: string;
+    path: string;
+}
+/**
+ * Valid UI theme identifiers for color themes.
+ */
+type UITheme = 'vs' | 'vs-dark' | 'hc-black' | 'hc-light';
+/**
+ * A color theme contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.themes
+ */
+interface ThemeContribution {
+    label: LocalizedString;
+    id?: string;
+    uiTheme: UITheme;
+    path: string;
+}
+/**
+ * An icon theme contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.iconThemes
+ */
+interface IconThemeContribution {
+    id: string;
+    label: LocalizedString;
+    path: string;
+}
+/**
+ * A product icon theme contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.productIconThemes
+ */
+interface ProductIconThemeContribution {
+    id: string;
+    label: LocalizedString;
+    path: string;
+}
+/**
+ * Color defaults for different themes.
+ */
+interface ColorDefaults {
+    light: string;
+    dark: string;
+    highContrast?: string;
+    highContrastLight?: string;
+}
+/**
+ * A color contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.colors
+ */
+interface ColorContribution {
+    id: string;
+    description: LocalizedString;
+    defaults: ColorDefaults;
+}
+/**
+ * The scope of a configuration setting.
+ */
+type ConfigurationScope = 'application' | 'machine' | 'machine-overridable' | 'window' | 'resource' | 'language-overridable';
+/**
+ * Presentation style for editing a configuration value.
+ */
+type EditPresentation = 'singlelineText' | 'multilineText';
+/**
+ * JSON Schema type values.
+ */
+type JsonSchemaType = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
+/**
+ * A configuration property schema, modeled after JSON Schema with VS Code
+ * extensions for scope, edit presentation, deprecation, etc.
+ */
+interface ConfigurationPropertySchema {
+    type?: JsonSchemaType | JsonSchemaType[];
+    default?: unknown;
+    description?: LocalizedString;
+    markdownDescription?: string;
+    scope?: ConfigurationScope;
+    enum?: unknown[];
+    enumDescriptions?: LocalizedString[];
+    enumItemLabels?: string[];
+    markdownEnumDescriptions?: string[];
+    deprecationMessage?: string;
+    markdownDeprecationMessage?: string;
+    editPresentation?: EditPresentation;
+    order?: number;
+    tags?: string[];
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    multipleOf?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    patternErrorMessage?: string;
+    format?: string;
+    items?: ConfigurationPropertySchema;
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    properties?: Record<string, ConfigurationPropertySchema>;
+    additionalProperties?: boolean | ConfigurationPropertySchema;
+    required?: string[];
+    oneOf?: ConfigurationPropertySchema[];
+    anyOf?: ConfigurationPropertySchema[];
+    allOf?: ConfigurationPropertySchema[];
+    if?: ConfigurationPropertySchema;
+    then?: ConfigurationPropertySchema;
+    else?: ConfigurationPropertySchema;
+}
+/**
+ * A configuration contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.configuration
+ */
+interface ConfigurationContribution {
+    title?: LocalizedString;
+    order?: number;
+    properties?: Record<string, ConfigurationPropertySchema>;
+}
+/**
+ * A JSON schema validation contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.jsonValidation
+ */
+interface JsonValidationContribution {
+    fileMatch: string | string[];
+    url: string;
+}
+/**
+ * A view container contribution (sidebar or panel).
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.viewsContainers
+ */
+interface ViewContainerContribution {
+    id: string;
+    title: LocalizedString;
+    icon: string;
+}
+/**
+ * View type discriminator.
+ */
+type ViewType = 'tree' | 'webview';
+/**
+ * View visibility state.
+ */
+type ViewVisibility = 'visible' | 'hidden' | 'collapsed';
+/**
+ * A view contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.views
+ */
+interface ViewContribution {
+    type?: ViewType;
+    id: string;
+    name: LocalizedString;
+    icon?: string;
+    when?: string;
+    contextualTitle?: LocalizedString;
+    visibility?: ViewVisibility;
+}
+/**
+ * A welcome view contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.viewsWelcome
+ */
+interface ViewWelcomeContribution {
+    view: string;
+    contents: LocalizedString;
+    when?: string;
+    group?: string;
+    enablement?: string;
+}
+/**
+ * A custom editor selector.
+ */
+interface CustomEditorSelector {
+    filenamePattern?: string;
+}
+/**
+ * Custom editor priority.
+ */
+type CustomEditorPriority = 'default' | 'builtin' | 'option';
+/**
+ * A custom editor contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.customEditors
+ */
+interface CustomEditorContribution {
+    viewType: string;
+    displayName: LocalizedString;
+    selector: CustomEditorSelector[];
+    priority?: CustomEditorPriority;
+}
+/**
+ * A debugger configuration snippet.
+ */
+interface DebugConfigurationSnippet {
+    label: string;
+    description?: string;
+    body: Record<string, unknown>;
+}
+/**
+ * A debugger contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.debuggers
+ */
+interface DebuggerContribution {
+    type: string;
+    label?: LocalizedString;
+    program?: string;
+    runtime?: string;
+    args?: string[];
+    runtimeArgs?: string[];
+    variables?: Record<string, string>;
+    initialConfigurations?: Record<string, unknown>[];
+    configurationSnippets?: DebugConfigurationSnippet[];
+    configurationAttributes?: Record<string, unknown>;
+    languages?: string[];
+    when?: string;
+    deprecated?: string;
+}
+/**
+ * A breakpoint contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.breakpoints
+ */
+interface BreakpointContribution {
+    language: string;
+    when?: string;
+}
+/**
+ * A task definition contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.taskDefinitions
+ */
+interface TaskDefinitionContribution {
+    type: string;
+    required?: string[];
+    properties?: Record<string, ConfigurationPropertySchema>;
+    when?: string;
+}
+/**
+ * Severity level for problem matchers.
+ */
+type ProblemSeverity = 'error' | 'warning' | 'info';
+/**
+ * Apply-to scope for problem matchers.
+ */
+type ProblemApplyTo = 'allDocuments' | 'openDocuments' | 'closedDocuments';
+/**
+ * File location style for problem matchers.
+ */
+type FileLocationKind = 'absolute' | 'relative' | 'autoDetect';
+/**
+ * Problem matcher background pattern.
+ */
+interface ProblemBackground {
+    activeOnStart?: boolean;
+    beginsPattern?: string;
+    endsPattern?: string;
+}
+/**
+ * A problem pattern contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.problemPatterns
+ */
+interface ProblemPatternContribution {
+    name?: string;
+    regexp: string;
+    message?: number;
+    file?: number;
+    location?: number;
+    line?: number;
+    column?: number;
+    endLine?: number;
+    endColumn?: number;
+    code?: number;
+    severity?: number;
+    loop?: boolean;
+    kind?: string;
+}
+/**
+ * A problem matcher contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.problemMatchers
+ */
+interface ProblemMatcherContribution {
+    name?: string;
+    label?: LocalizedString;
+    owner?: string;
+    source?: string;
+    applyTo?: ProblemApplyTo;
+    fileLocation?: FileLocationKind | [FileLocationKind, string];
+    pattern?: ProblemPatternContribution | ProblemPatternContribution[] | string;
+    severity?: ProblemSeverity;
+    background?: ProblemBackground;
+}
+/**
+ * A notebook selector for matching notebooks by type.
+ */
+interface NotebookSelector {
+    filenamePattern?: string;
+    excludeFileNamePattern?: string;
+}
+/**
+ * A notebook contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.notebooks
+ */
+interface NotebookContribution {
+    type: string;
+    displayName: LocalizedString;
+    selector: NotebookSelector[];
+    priority?: 'default' | 'option';
+}
+/**
+ * Messaging requirement for notebook renderers.
+ */
+type NotebookRendererMessaging = 'always' | 'optional' | 'never';
+/**
+ * A notebook renderer contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.notebookRenderer
+ */
+interface NotebookRendererContribution {
+    id: string;
+    displayName: LocalizedString;
+    mimeTypes: string[];
+    entrypoint: string | {
+        extends: string;
+        path: string;
+    };
+    dependencies?: string[];
+    requiresMessaging?: NotebookRendererMessaging;
+}
+/**
+ * An authentication provider contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.authentication
+ */
+interface AuthenticationContribution {
+    id: string;
+    label: LocalizedString;
+}
+/**
+ * Walkthrough step media — one of image, markdown, or SVG.
+ */
+interface WalkthroughStepMedia {
+    image?: string | {
+        light: string;
+        dark: string;
+        hc: string;
+        hcLight: string;
+    };
+    markdown?: string;
+    svg?: string;
+    altText?: string;
+}
+/**
+ * A walkthrough step contribution.
+ */
+interface WalkthroughStepContribution {
+    id: string;
+    title: LocalizedString;
+    description: LocalizedString;
+    media: WalkthroughStepMedia;
+    completionEvents?: string[];
+    when?: string;
+}
+/**
+ * A walkthrough contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.walkthroughs
+ */
+interface WalkthroughContribution {
+    id: string;
+    title: LocalizedString;
+    icon?: string;
+    description: LocalizedString;
+    featuredFor?: string[];
+    when?: string;
+    steps: WalkthroughStepContribution[];
+}
+/**
+ * A localization translation entry.
+ */
+interface LocalizationTranslation {
+    id: string;
+    path: string;
+}
+/**
+ * A localization contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.localizations
+ */
+interface LocalizationContribution {
+    languageId: string;
+    languageName?: string;
+    localizedLanguageName?: string;
+    translations: LocalizationTranslation[];
+}
+/**
+ * A code action kind with title.
+ *
+ * @internal This contribution point is used internally by VS Code but is not
+ * part of the official stable extension API documentation. Included for
+ * completeness when parsing real-world manifests that may declare it.
+ */
+interface CodeActionKindEntry {
+    kind: string;
+    title: LocalizedString;
+    description?: LocalizedString;
+}
+/**
+ * A code action contribution.
+ *
+ * @internal This contribution point is used internally by VS Code but is not
+ * part of the official stable extension API documentation. Included for
+ * completeness when parsing real-world manifests that may declare it.
+ */
+interface CodeActionContribution {
+    languages: string[];
+    actions: CodeActionKindEntry[];
+}
+/**
+ * A semantic token type contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.semanticTokenTypes
+ */
+interface SemanticTokenTypeContribution {
+    id: string;
+    superType?: string;
+    description?: LocalizedString;
+}
+/**
+ * A semantic token modifier contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.semanticTokenModifiers
+ */
+interface SemanticTokenModifierContribution {
+    id: string;
+    description?: LocalizedString;
+}
+/**
+ * A semantic token scope map contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.semanticTokenScopes
+ */
+interface SemanticTokenScopeContribution {
+    language?: string;
+    scopes: Record<string, string[]>;
+}
+/**
+ * A resource label formatter contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.resourceLabelFormatters
+ */
+interface ResourceLabelFormatterContribution {
+    scheme: string;
+    authority?: string;
+    formatting: {
+        label: string;
+        separator?: string;
+        stripPathStartingSeparator?: boolean;
+        tildify?: boolean;
+        workspaceSuffix?: string;
+    };
+}
+/**
+ * A terminal profile contribution.
+ */
+interface TerminalProfile {
+    id: string;
+    title: LocalizedString;
+    icon?: IconReference;
+}
+/**
+ * Terminal contributions.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.terminal
+ */
+interface TerminalContribution {
+    profiles?: TerminalProfile[];
+}
+/**
+ * Default icon definition with font path and character.
+ */
+interface IconDefault {
+    fontPath: string;
+    fontCharacter: string;
+}
+/**
+ * An icon contribution.
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.icons
+ */
+interface IconContribution {
+    description: LocalizedString;
+    default: IconDefault;
+}
+/**
+ * A TypeScript server plugin contribution.
+ *
+ * Enables extensions to provide TypeScript language service plugins that
+ * enhance the editor's TypeScript/JavaScript language features.
+ *
+ * @see https://code.visualstudio.com/api/references/contribution-points#contributes.typescriptServerPlugins
+ */
+interface TypescriptServerPluginContribution {
+    /** The npm module name of the TypeScript server plugin. */
+    name: string;
+    /** Whether to enable the plugin for JavaScript files. Defaults to false. */
+    enableForWorkspaceTypeScriptVersions?: boolean;
+    /** Languages supported by this plugin. */
+    languages?: string[];
+}
+/**
+ * A start entry contribution (displayed on the Start page).
+ *
+ * @internal This contribution point is used internally by VS Code but is not
+ * part of the official stable extension API documentation. Included for
+ * completeness when parsing real-world manifests that may declare it.
+ */
+interface StartEntryContribution {
+    title: LocalizedString;
+    description?: LocalizedString;
+    command: string;
+    when?: string;
+    category?: LocalizedString;
+}
+/**
+ * All stable VS Code extension contribution points.
+ *
+ * Each contribution point maps to a named interface above.
+ * Menu items are keyed by menu location (e.g., `editor/context`,
+ * `commandPalette`, `view/title`, etc.).
+ *
+ * @see https://code.visualstudio.com/api/references/contribution-points
+ */
+interface VSCodeContributes {
+    commands?: CommandContribution[];
+    menus?: Record<string, MenuContribution[]>;
+    submenus?: SubmenuContribution[];
+    keybindings?: KeybindingContribution[];
+    languages?: LanguageContribution[];
+    grammars?: GrammarContribution[];
+    snippets?: SnippetContribution[];
+    themes?: ThemeContribution[];
+    iconThemes?: IconThemeContribution[];
+    productIconThemes?: ProductIconThemeContribution[];
+    colors?: ColorContribution[];
+    configuration?: ConfigurationContribution | ConfigurationContribution[];
+    configurationDefaults?: Record<string, unknown>;
+    jsonValidation?: JsonValidationContribution[];
+    viewsContainers?: Record<string, ViewContainerContribution[]>;
+    views?: Record<string, ViewContribution[]>;
+    viewsWelcome?: ViewWelcomeContribution[];
+    customEditors?: CustomEditorContribution[];
+    debuggers?: DebuggerContribution[];
+    breakpoints?: BreakpointContribution[];
+    taskDefinitions?: TaskDefinitionContribution[];
+    problemMatchers?: ProblemMatcherContribution[];
+    problemPatterns?: ProblemPatternContribution[];
+    notebooks?: NotebookContribution[];
+    notebookRenderer?: NotebookRendererContribution[];
+    authentication?: AuthenticationContribution[];
+    walkthroughs?: WalkthroughContribution[];
+    localizations?: LocalizationContribution[];
+    codeActions?: CodeActionContribution[];
+    semanticTokenTypes?: SemanticTokenTypeContribution[];
+    semanticTokenModifiers?: SemanticTokenModifierContribution[];
+    semanticTokenScopes?: SemanticTokenScopeContribution[];
+    resourceLabelFormatters?: ResourceLabelFormatterContribution[];
+    terminal?: TerminalContribution;
+    icons?: Record<string, IconContribution>;
+    typescriptServerPlugins?: TypescriptServerPluginContribution[];
+    startEntries?: StartEntryContribution[];
+}
+/**
+ * The full VS Code extension package.json manifest.
+ *
+ * This interface covers all standard and VS-Code-specific fields that an
+ * extension can declare. The three required fields are `name`, `publisher`,
+ * and `version`.
+ *
+ * @see https://code.visualstudio.com/api/references/extension-manifest
+ */
+interface VSCodeExtensionManifest {
+    /** The extension identifier (npm package name). */
+    name: string;
+    /** The publisher identifier (marketplace publisher ID). */
+    publisher: string;
+    /** The extension version (semver). */
+    version: string;
+    /** Engine compatibility — `vscode` key is required. */
+    engines: {
+        vscode: string;
+    };
+    /** Human-readable display name. */
+    displayName?: LocalizedString;
+    /** Short description of the extension. */
+    description?: LocalizedString;
+    /** Marketplace categories. */
+    categories?: ExtensionCategory[];
+    /** Marketplace keywords (max 5). */
+    keywords?: string[];
+    /** Relative path to the extension icon (128x128 PNG). */
+    icon?: string;
+    /** If true, the extension is marked as Preview in the marketplace. */
+    preview?: boolean;
+    /** Badges displayed on the marketplace page. */
+    badges?: Badge[];
+    /** Markdown rendering engine — `'github'` or `'standard'`. */
+    markdown?: 'github' | 'standard';
+    /** Q&A link — `'marketplace'`, `false`, or a URL string. */
+    qna?: 'marketplace' | false | string;
+    /** Pricing model — `'Free'` or `'Trial'`. */
+    pricing?: 'Free' | 'Trial';
+    /** Gallery banner appearance on the marketplace detail page. */
+    galleryBanner?: {
+        color?: string;
+        theme?: 'dark' | 'light';
+    };
+    /** Sponsor link displayed on the marketplace page. */
+    sponsor?: {
+        url: string;
+    };
+    /** Path to the extension's main entry point (Node.js). */
+    main?: string;
+    /** Path to the extension's browser entry point. */
+    browser?: string;
+    /** Events that trigger extension activation. */
+    activationEvents?: string[];
+    /** Where the extension should run. */
+    extensionKind?: ExtensionKind[];
+    /** Extension IDs that this extension depends on. */
+    extensionDependencies?: string[];
+    /** Extension IDs bundled together as an extension pack. */
+    extensionPack?: string[];
+    /** Capability declarations (untrusted/virtual workspace support). */
+    capabilities?: ExtensionCapabilities;
+    /** All contribution points. */
+    contributes?: VSCodeContributes;
+    /** Path to the localization bundle directory. */
+    l10n?: string;
+    /** Repository information. */
+    repository?: RepositoryReference;
+    /** Bug tracker information. */
+    bugs?: BugsReference;
+    /** Extension homepage URL. */
+    homepage?: string;
+    /** SPDX license identifier. */
+    license?: string;
+    /** npm scripts. */
+    scripts?: Record<string, string>;
+    /** Runtime dependencies. */
+    dependencies?: Record<string, string>;
+    /** Development dependencies. */
+    devDependencies?: Record<string, string>;
+}
+
+/**
+ * Types for installed extensions, compatibility assessment, and VSIX scanning.
+ *
+ * These types model the unified extension storage format shared across all
+ * FlowState platforms (Tauri desktop, Next.js web, mobile, sidecar).
+ *
+ * @see https://code.visualstudio.com/api/references/extension-manifest
+ */
+
+/**
+ * Overall compatibility level for a VS Code extension in FlowState.
+ *
+ * - `'full'` — All contribution points and APIs are supported
+ * - `'partial'` — Some contribution points work, others require unavailable runtime
+ * - `'declarative-only'` — Only declarative contributions (themes, snippets, grammars) work
+ * - `'unsupported'` — Extension cannot run in FlowState
+ */
+type CompatibilityLevel = 'full' | 'partial' | 'declarative-only' | 'unsupported';
+/**
+ * Detailed compatibility assessment for a VS Code extension.
+ *
+ * Produced by the compatibility scoring algorithm after scanning an extension's
+ * manifest and (optionally) its source code for API namespace usage.
+ */
+interface CompatibilityReport {
+    /** Overall compatibility level. */
+    level: CompatibilityLevel;
+    /** Contribution points that FlowState can handle on the current platform. */
+    supported: string[];
+    /** Contribution points that require runtime not yet available. */
+    unsupported: string[];
+    /** VS Code API namespaces detected via static analysis (e.g., `'vscode.window'`, `'vscode.workspace'`). */
+    apiNamespacesUsed: string[];
+    /** User-facing warning messages about compatibility limitations. */
+    warnings: string[];
+}
+/**
+ * Source format of an installed extension.
+ *
+ * - `'fsext'` — Native FlowState extension package
+ * - `'vsix'` — VS Code extension (from Open VSX or sideloaded)
+ * - `'builtin'` — Bundled with FlowState
+ */
+type ExtensionSource = 'fsext' | 'vsix' | 'builtin';
+/**
+ * Registry from which an extension was obtained.
+ *
+ * - `'flowstate'` — FlowState marketplace
+ * - `'openvsx'` — Open VSX registry
+ */
+type ExtensionRegistry = 'flowstate' | 'openvsx';
+/**
+ * Installation scope of an extension.
+ *
+ * - `'user'` — Available across all workspaces for this user
+ * - `'workspace'` — Only available in a specific workspace
+ */
+type ExtensionScope = 'user' | 'workspace';
+/**
+ * Minimal FlowState plugin manifest shape used by extension-core.
+ *
+ * This captures the essential fields without importing from `flowstate-app-framework`,
+ * keeping `extension-core` zero-dependency. Consumers can intersect this with the
+ * full `PluginManifest` type from the framework package when needed.
+ */
+interface FlowStateManifest {
+    /** Unique plugin identifier. */
+    id: string;
+    /** Human-readable display name. */
+    displayName: string;
+    /** Semantic version. */
+    version: string;
+    /** Publisher or author name. */
+    publisher?: string;
+    /** Path to the main entry point module. */
+    main: string;
+    /** Path to the browser-specific entry point. */
+    browser?: string;
+    /** Plugin category. */
+    category?: string;
+    /** FlowState extension type inferred from the manifest. */
+    extensionType?: string;
+    /** Activation events controlling when the extension loads. */
+    activationEvents?: string[];
+    /** Contribution points for extending FlowState. */
+    contributes?: Record<string, unknown>;
+}
+/**
+ * Unified storage model for installed extensions.
+ *
+ * Both `.fsext` (native FlowState) and `.vsix` (VS Code) extensions resolve
+ * to this record after installation. This is the canonical shape stored in
+ * the local extension database across all platforms.
+ */
+interface InstalledExtension {
+    /** Publisher/name identifier (e.g., `'esbenp.prettier-vscode'`). */
+    id: string;
+    /** Publisher namespace. */
+    publisher: string;
+    /** Extension name within namespace. */
+    name: string;
+    /** Installed version (semver). */
+    version: string;
+    /** Human-readable display name. */
+    displayName: string;
+    /** Source format of the extension. */
+    source: ExtensionSource;
+    /** Registry from which the extension was obtained. */
+    registry: ExtensionRegistry;
+    /** Translated FlowState manifest. */
+    manifest: FlowStateManifest;
+    /** Original VS Code manifest (present when `source` is `'vsix'`). */
+    vsCodeManifest?: VSCodeExtensionManifest;
+    /** Installation scope. */
+    scope: ExtensionScope;
+    /** Whether the extension is currently enabled. */
+    enabled: boolean;
+    /** ISO 8601 timestamp of when the extension was installed. */
+    installedAt: string;
+    /** Path to the extracted extension files on disk. */
+    extensionPath: string;
+    /** Compatibility assessment for the current platform. */
+    compatibility: CompatibilityReport;
+}
+/**
+ * Result of scanning a `.vsix` archive.
+ *
+ * Produced by the VSIX scanner after unpacking, manifest extraction,
+ * validation, classification, and compatibility assessment.
+ */
+interface VsixScanResult {
+    /** Original VS Code extension manifest (package.json). */
+    vsCodeManifest: VSCodeExtensionManifest;
+    /** Translated FlowState manifest. */
+    flowstateManifest: FlowStateManifest;
+    /** Whether this extension uses only declarative contribution points. */
+    isDeclarative: boolean;
+    /** List of contribution point keys used by the extension. */
+    contributionPoints: string[];
+    /**
+     * Extracted asset files keyed by relative path.
+     *
+     * Uses `Uint8Array` instead of `Buffer` for cross-platform compatibility
+     * (works in browsers, Node.js, Deno, and Tauri WebView).
+     */
+    assets: Map<string, Uint8Array>;
+    /** Runtime compatibility assessment. */
+    compatibility: CompatibilityReport;
+}
+
+/**
+ * Manifest adapter for bidirectional translation between VS Code and FlowState formats.
+ *
+ * - `vsCodeToFlowState()` — converts VS Code `package.json` → `FlowStateManifest`
+ * - `flowStateToVsCode()` — converts `FlowStateManifest` → `Partial<VSCodeExtensionManifest>`
+ *
+ * Both functions are pure, deterministic, and side-effect free.
+ */
+
+/**
+ * Map a VS Code marketplace category to its FlowState equivalent.
+ *
+ * @param vsCodeCategory - The VS Code category string (e.g., `'Programming Languages'`)
+ * @returns The kebab-case FlowState category, or `undefined` if unmapped
+ */
+declare function mapCategory(vsCodeCategory: string | undefined): string | undefined;
+/**
+ * Map VS Code activation events to FlowState activation events.
+ *
+ * Most events pass through as-is. The notable mapping is:
+ * - `onStartupFinished` → `onStartup`
+ *
+ * @param manifest - The VS Code extension manifest
+ * @returns Array of FlowState activation event strings
+ */
+declare function mapActivationEvents(manifest: VSCodeExtensionManifest): string[];
+/**
+ * Infer the FlowState extension type from a VS Code manifest.
+ *
+ * Uses the following heuristics:
+ * 1. If the extension only contributes `themes`, `iconThemes`, or `productIconThemes` → `'theme'`
+ * 2. If the extension contributes `localizations` → `'pack'` (language pack)
+ * 3. If `extensionKind` includes `'workspace'` → `'app'`
+ * 4. Default → `'ui-extension'`
+ *
+ * @param manifest - The VS Code extension manifest
+ * @returns The FlowState extension type string
+ */
+declare function mapExtensionKind(manifest: VSCodeExtensionManifest): string;
+/**
+ * Translate a VS Code extension manifest to a FlowState manifest.
+ *
+ * This is a pure function that maps VS Code `package.json` fields to the
+ * equivalent FlowState `FlowStateManifest` shape. The translation is:
+ *
+ * - **Lossless** for declarative fields (themes, snippets, grammars, etc.)
+ * - **Deterministic** — same input always produces same output
+ * - **Side-effect free** — no I/O, no mutations
+ *
+ * @param manifest - A VS Code extension package.json parsed as `VSCodeExtensionManifest`
+ * @returns A `FlowStateManifest` suitable for FlowState's extension system
+ *
+ * @example
+ * ```typescript
+ * const vsCodeManifest: VSCodeExtensionManifest = {
+ *   name: 'prettier-vscode',
+ *   publisher: 'esbenp',
+ *   version: '10.1.0',
+ *   engines: { vscode: '^1.80.0' },
+ *   main: './dist/extension.js',
+ * };
+ *
+ * const flowstateManifest = vsCodeToFlowState(vsCodeManifest);
+ * // { id: 'esbenp.prettier-vscode', displayName: 'prettier-vscode', ... }
+ * ```
+ */
+declare function vsCodeToFlowState(manifest: VSCodeExtensionManifest): FlowStateManifest;
+/**
+ * Map a FlowState category back to its VS Code marketplace equivalent.
+ *
+ * @param flowstateCategory - The kebab-case FlowState category (e.g., `'programming-languages'`)
+ * @returns The VS Code Title Case category, or `undefined` if unmapped
+ */
+declare function reverseCategory(flowstateCategory: string | undefined): string | undefined;
+/**
+ * Reverse map FlowState activation events back to VS Code format.
+ *
+ * - `onStartup` → `onStartupFinished`
+ * - All other events pass through as-is
+ *
+ * @param events - FlowState activation event strings
+ * @returns Array of VS Code activation event strings
+ */
+declare function reverseActivationEvents(events: string[] | undefined): string[];
+/**
+ * Map a FlowState extension type back to VS Code `extensionKind`.
+ *
+ * - `'app'` → `['workspace']`
+ * - `'theme'` → `['ui']`
+ * - `'pack'` → `['ui']`
+ * - `'ui-extension'` or `undefined` → `undefined` (VS Code default)
+ *
+ * @param extensionType - The FlowState extension type
+ * @returns VS Code `extensionKind` array, or `undefined` for default
+ */
+declare function reverseExtensionKind(extensionType: string | undefined): Array<'ui' | 'workspace'> | undefined;
+/**
+ * Translate a FlowState manifest back to a VS Code extension manifest.
+ *
+ * This is a pure function that maps `FlowStateManifest` fields to the
+ * equivalent VS Code `package.json` shape. The result is `Partial` because
+ * some required VS Code fields (like `engines.vscode`) cannot be inferred
+ * from a FlowState manifest alone.
+ *
+ * FlowState-specific metadata is stored under the `flowstate` key in the
+ * output for round-trip preservation.
+ *
+ * @param manifest - A FlowState manifest
+ * @returns A partial VS Code extension manifest suitable for cross-publishing
+ *
+ * @example
+ * ```typescript
+ * const fsManifest: FlowStateManifest = {
+ *   id: 'esbenp.prettier-vscode',
+ *   displayName: 'Prettier',
+ *   version: '10.1.0',
+ *   main: './dist/extension.js',
+ * };
+ *
+ * const vsCodeManifest = flowStateToVsCode(fsManifest);
+ * // { name: 'prettier-vscode', publisher: 'esbenp', version: '10.1.0', ... }
+ * ```
+ */
+declare function flowStateToVsCode(manifest: FlowStateManifest): Partial<VSCodeExtensionManifest>;
+
+/**
+ * Contribution point keys that are purely declarative (no runtime code needed).
+ *
+ * Extensions using only these contribution points can run in FlowState without
+ * a VS Code extension host.
+ */
+declare const DECLARATIVE_CONTRIBUTION_POINTS: Set<string>;
+/** Error codes for VSIX scanning failures. */
+type VsixScanErrorCode = 'INVALID_ZIP' | 'MISSING_MANIFEST' | 'INVALID_MANIFEST';
+/**
+ * Typed error thrown by the VSIX scanner.
+ */
+declare class VsixScanError extends Error {
+    readonly code: VsixScanErrorCode;
+    constructor(code: VsixScanErrorCode, message: string);
+}
+/**
+ * Determine whether an extension uses only declarative contribution points.
+ *
+ * An extension is declarative if:
+ * 1. It has no `main` or `browser` entry point
+ * 2. All of its contribution point keys are in the declarative set
+ *
+ * @param manifest - The VS Code extension manifest
+ * @returns `true` if the extension is purely declarative
+ */
+declare function classifyDeclarative(manifest: VSCodeExtensionManifest): boolean;
+/**
+ * Enumerate all active contribution point keys from a manifest.
+ *
+ * @param manifest - The VS Code extension manifest
+ * @returns Sorted array of contribution point keys with non-empty values
+ */
+declare function enumerateContributionPoints(manifest: VSCodeExtensionManifest): string[];
+/**
+ * Scan JS files in an asset map for VS Code API namespace usage.
+ *
+ * This is best-effort static analysis using regex matching, not a full parser.
+ * It looks for `vscode.<namespace>` patterns in `.js` files.
+ *
+ * @param assets - Map of relative file paths to file contents
+ * @returns Deduplicated, sorted array of `vscode.<namespace>` strings
+ */
+declare function detectApiNamespaces(assets: Map<string, Uint8Array>): string[];
+/**
+ * Build a compatibility report from manifest analysis and API detection.
+ *
+ * @param manifest - The VS Code extension manifest
+ * @param apiNamespaces - Detected API namespace strings
+ * @returns A complete `CompatibilityReport`
+ */
+declare function buildCompatibilityReport(manifest: VSCodeExtensionManifest, apiNamespaces: string[]): CompatibilityReport;
+/**
+ * Scan a VSIX archive and produce a complete scan result.
+ *
+ * @param data - The raw VSIX file contents as a `Uint8Array`
+ * @returns A `VsixScanResult` with manifest, classification, and compatibility data
+ *
+ * @throws {VsixScanError} With code `'INVALID_ZIP'` if decompression fails
+ * @throws {VsixScanError} With code `'MISSING_MANIFEST'` if `extension/package.json` not found
+ * @throws {VsixScanError} With code `'INVALID_MANIFEST'` if manifest JSON is invalid or missing required fields
+ *
+ * @example
+ * ```typescript
+ * const vsixData = await fetch(vsixUrl).then(r => r.arrayBuffer());
+ * const result = scanVsix(new Uint8Array(vsixData));
+ * console.log(result.isDeclarative); // true for theme extensions
+ * ```
+ */
+declare function scanVsix(data: Uint8Array): VsixScanResult;
+
+/**
+ * Platform-aware compatibility scoring for VS Code extensions.
+ *
+ * Evaluates extensions against FlowState's supported capabilities per platform
+ * (desktop, web, mobile) and produces a numeric score, compatibility level,
+ * per-contribution-point breakdown, and actionable recommendations.
+ */
+
+/** Target platform for compatibility evaluation. */
+type Platform = 'desktop' | 'web' | 'mobile';
+/** Support status for a contribution point on a given platform. */
+type SupportStatus = 'native' | 'polyfill' | 'partial' | 'unsupported';
+/** Compatibility score for a single contribution point. */
+interface ContributionPointScore {
+    /** The contribution point key (e.g., `'themes'`, `'commands'`). */
+    key: string;
+    /** Support status on the target platform. */
+    status: SupportStatus;
+    /** Numeric weight derived from the support status (0–1). */
+    weight: number;
+}
+/** Complete compatibility score for an extension on a target platform. */
+interface CompatibilityScore {
+    /** Numeric score from 0 to 100. */
+    score: number;
+    /** Compatibility level derived from the numeric score. */
+    level: CompatibilityLevel;
+    /** The platform this score was computed for. */
+    platform: Platform;
+    /** Per-contribution-point breakdown. */
+    breakdown: ContributionPointScore[];
+    /** Base compatibility report from the scanner. */
+    report: CompatibilityReport;
+    /** Actionable recommendations for improving compatibility. */
+    recommendations: string[];
+}
+/**
+ * Numeric weights for each support status.
+ *
+ * - `native` = 1.0 — FlowState handles this natively
+ * - `polyfill` = 0.8 — Works via compatibility layer
+ * - `partial` = 0.5 — Some features work
+ * - `unsupported` = 0 — Cannot run
+ */
+declare const SUPPORT_WEIGHTS: Record<SupportStatus, number>;
+/**
+ * Platform support matrix mapping each contribution point to its support
+ * status per platform.
+ *
+ * Desktop (Tauri) supports the most contribution points.
+ * Web (Next.js) supports declarative + some UI contributions.
+ * Mobile supports only basic declarative contributions.
+ */
+declare const PLATFORM_SUPPORT: Record<Platform, Record<string, SupportStatus>>;
+/**
+ * Returns the support matrix for a given platform.
+ *
+ * Contribution points not present in the matrix are considered `'unsupported'`.
+ *
+ * @param platform - The target platform
+ * @returns Map of contribution point keys to their support status
+ */
+declare function getPlatformSupport(platform: Platform): Record<string, SupportStatus>;
+/**
+ * Score a VS Code extension's compatibility with a target platform.
+ *
+ * @param manifest - The VS Code extension manifest
+ * @param platform - The target platform to score against
+ * @param apiNamespaces - Optional array of detected API namespace strings
+ * @returns A complete `CompatibilityScore`
+ */
+declare function scoreExtension(manifest: VSCodeExtensionManifest, platform: Platform, apiNamespaces?: string[]): CompatibilityScore;
+/**
+ * Generate actionable recommendations based on the scoring breakdown.
+ *
+ * @param breakdown - Per-contribution-point score breakdown
+ * @param manifest - The VS Code extension manifest
+ * @param platform - The target platform
+ * @returns Array of recommendation strings
+ */
+declare function generateRecommendations(breakdown: ContributionPointScore[], manifest: VSCodeExtensionManifest, platform: Platform): string[];
+
+/**
+ * Extension dependency resolver — builds a dependency graph from VS Code
+ * extension manifests and produces a topologically sorted installation order.
+ *
+ * Handles both `extensionDependencies` (hard dependencies) and `extensionPack`
+ * (pack members). Detects circular dependencies using Kahn's algorithm.
+ */
+
+/** A node in the dependency graph representing a single extension. */
+interface ExtensionNode {
+    /** Normalized `publisher.name` identifier. */
+    id: string;
+    /** Hard dependency extension IDs. */
+    extensionDependencies: string[];
+    /** Pack member extension IDs. */
+    extensionPack: string[];
+}
+/** A directed edge in the dependency graph. */
+interface DependencyEdge {
+    /** The dependent extension (the one that requires the other). */
+    from: string;
+    /** The dependency (the one that must be installed first). */
+    to: string;
+    /** Edge type — `'dependency'` for hard deps, `'pack'` for pack members. */
+    type: 'dependency' | 'pack';
+}
+/** The complete dependency graph structure. */
+interface DependencyGraph {
+    /** All known extension nodes keyed by normalized ID. */
+    nodes: Map<string, ExtensionNode>;
+    /** All directed edges in the graph. */
+    edges: DependencyEdge[];
+    /** Adjacency list: extension ID → set of IDs it depends on. */
+    adjacency: Map<string, Set<string>>;
+}
+/** Successful resolution with a sorted installation order. */
+interface DependencyResolutionSuccess {
+    ok: true;
+    /** Extension IDs in topological order (install first → last). */
+    order: string[];
+    /** The underlying dependency graph. */
+    graph: DependencyGraph;
+}
+/** Failed resolution due to circular dependencies. */
+interface DependencyResolutionError {
+    ok: false;
+    /** The type of error. */
+    error: 'circular-dependency';
+    /** Extension IDs involved in the cycle(s). */
+    participants: string[];
+    /** The underlying dependency graph. */
+    graph: DependencyGraph;
+}
+/** Result of dependency resolution — either success or error. */
+type DependencyResolution = DependencyResolutionSuccess | DependencyResolutionError;
+/**
+ * Normalize an extension ID for case-insensitive matching.
+ *
+ * VS Code marketplace treats extension IDs as case-insensitive.
+ *
+ * @param id - The extension ID (e.g., `'EsbenP.prettier-vscode'`)
+ * @returns Lowercased ID (e.g., `'esbenp.prettier-vscode'`)
+ */
+declare function normalizeExtensionId(id: string): string;
+/**
+ * Extract an `ExtensionNode` from a VS Code extension manifest.
+ *
+ * @param manifest - The VS Code extension manifest
+ * @returns An `ExtensionNode` with normalized IDs
+ */
+declare function extractDependencyNode(manifest: VSCodeExtensionManifest): ExtensionNode;
+/**
+ * Build a dependency graph from an array of extension nodes.
+ *
+ * Dependencies that reference extensions not in the input set are added
+ * as leaf nodes (no dependencies of their own).
+ *
+ * @param nodes - Array of extension nodes
+ * @returns A complete `DependencyGraph`
+ */
+declare function buildDependencyGraph(nodes: ExtensionNode[]): DependencyGraph;
+/**
+ * Resolve dependencies and produce a topologically sorted installation order.
+ *
+ * Uses Kahn's algorithm (BFS-based topological sort) for deterministic ordering
+ * and straightforward cycle detection. Extensions with no dependencies appear
+ * first in the result.
+ *
+ * @param nodes - Array of extension nodes to resolve
+ * @returns A `DependencyResolution` — either success with sorted order, or error with cycle participants
+ */
+declare function resolveDependencies(nodes: ExtensionNode[]): DependencyResolution;
+
+/**
+ * TypeScript types for the Open VSX Registry REST API.
+ *
+ * These types model the request parameters and response shapes for the
+ * public Open VSX API at https://open-vsx.org/api.
+ *
+ * @see https://github.com/eclipse/openvsx/wiki/Using-the-Registry-API
+ */
+/**
+ * Target platform identifiers used by VS Code and Open VSX.
+ *
+ * Extensions can be published for specific platforms (e.g., native binaries)
+ * or as `'universal'` (platform-independent).
+ */
+type OpenVSXTargetPlatform = 'universal' | 'win32-x64' | 'win32-ia32' | 'win32-arm64' | 'linux-x64' | 'linux-arm64' | 'linux-armhf' | 'alpine-x64' | 'alpine-arm64' | 'darwin-x64' | 'darwin-arm64' | 'web';
+/**
+ * Sort field for search results.
+ */
+type OpenVSXSearchSortBy = 'relevance' | 'timestamp' | 'rating' | 'downloadCount';
+/**
+ * Open VSX user / publisher information.
+ */
+interface OpenVSXUser {
+    /** Login name (e.g., `'ms-python'`). */
+    loginName: string;
+    /** Display name (may be absent). */
+    fullName?: string;
+    /** Avatar image URL. */
+    avatarUrl: string;
+    /** User homepage URL. */
+    homepage: string;
+    /** OAuth provider (e.g., `'github'`). */
+    provider: string;
+}
+/**
+ * Map of file type to download URL for an extension version.
+ *
+ * All values are URLs. Not all keys are present for every extension.
+ */
+interface OpenVSXFileMap {
+    /** VSIX package download URL. */
+    download: string;
+    /** Extension manifest (package.json) URL. */
+    manifest?: string;
+    /** README content URL. */
+    readme?: string;
+    /** LICENSE file URL. */
+    license?: string;
+    /** CHANGELOG URL. */
+    changelog?: string;
+    /** Extension icon image URL. */
+    icon?: string;
+    /** VS Code extension.vsixmanifest URL. */
+    vsixmanifest?: string;
+    /** SHA-256 checksum URL. */
+    sha256?: string;
+    /** Signature file (.sigzip) URL. */
+    signature?: string;
+    /** Public key URL for signature verification. */
+    publicKey?: string;
+}
+/**
+ * Request parameters for `GET /api/-/search`.
+ */
+interface OpenVSXSearchParams {
+    /** Free-text search term. */
+    query?: string;
+    /** Filter by extension category. */
+    category?: string;
+    /** Filter by target platform. */
+    targetPlatform?: OpenVSXTargetPlatform;
+    /** Number of results per page (default: 18). */
+    size?: number;
+    /** Zero-based page offset (default: 0). */
+    offset?: number;
+    /** Sort direction. */
+    sortOrder?: 'asc' | 'desc';
+    /** Sort field. */
+    sortBy?: OpenVSXSearchSortBy;
+    /** Include all versions in results (default: false). */
+    includeAllVersions?: boolean;
+}
+/**
+ * A single extension entry in search results.
+ */
+interface OpenVSXSearchEntry {
+    /** API URL for this extension. */
+    url: string;
+    /** File download URLs. */
+    files: OpenVSXFileMap;
+    /** Extension name (e.g., `'python'`). */
+    name: string;
+    /** Namespace / publisher (e.g., `'ms-python'`). */
+    namespace: string;
+    /** Latest version string. */
+    version: string;
+    /** ISO 8601 publication timestamp. */
+    timestamp: string;
+    /** Whether the publisher is verified. */
+    verified: boolean;
+    /** Average rating (0–5 scale), absent if no reviews. */
+    averageRating?: number;
+    /** Number of reviews. */
+    reviewCount?: number;
+    /** Total download count. */
+    downloadCount: number;
+    /** Display name for UI. */
+    displayName: string;
+    /** Short description. */
+    description: string;
+    /** Whether the extension is deprecated. */
+    deprecated: boolean;
+}
+/**
+ * Response from `GET /api/-/search`.
+ */
+interface OpenVSXSearchResult {
+    /** Echo of the requested offset. */
+    offset: number;
+    /** Total number of matching extensions. */
+    totalSize: number;
+    /** Extensions on this page. */
+    extensions: OpenVSXSearchEntry[];
+}
+/**
+ * Full extension metadata returned by `GET /api/{namespace}/{extension}`.
+ */
+interface OpenVSXExtension {
+    /** Namespace API URL. */
+    namespaceUrl: string;
+    /** Reviews API URL. */
+    reviewsUrl: string;
+    /** Extension API URL. */
+    url?: string;
+    /** All versions API URL. */
+    allVersionsUrl: string;
+    /** File download URLs for this version. */
+    files: OpenVSXFileMap;
+    /** Extension name. */
+    name: string;
+    /** Namespace / publisher. */
+    namespace: string;
+    /** Version string. */
+    version: string;
+    /** Target platform (e.g., `'universal'`). */
+    targetPlatform: string;
+    /** Publisher information. */
+    publishedBy: OpenVSXUser;
+    /** Whether the publisher is verified. */
+    verified: boolean;
+    /** Whether publisher is unrelated to namespace owner. */
+    unrelatedPublisher: boolean;
+    /** Namespace access level (e.g., `'restricted'`). */
+    namespaceAccess: string;
+    /** Map of version string → API URL. */
+    allVersions: Record<string, string>;
+    /** Total download count. */
+    downloadCount: number;
+    /** Number of reviews. */
+    reviewCount: number;
+    /** ISO 8601 publication timestamp. */
+    timestamp: string;
+    /** Version aliases (e.g., `['latest']`). */
+    versionAlias: string[];
+    /** Whether this is a pre-release version. */
+    preRelease: boolean;
+    /** Whether this is a preview extension. */
+    preview: boolean;
+    /** Whether this extension is deprecated. */
+    deprecated: boolean;
+    /** Whether this extension is downloadable. */
+    downloadable: boolean;
+    /** Display name for UI. */
+    displayName: string;
+    /** Namespace display name. */
+    namespaceDisplayName: string;
+    /** Short description. */
+    description: string;
+    /** Engine compatibility (e.g., `{ vscode: '^1.75.0' }`). */
+    engines: Record<string, string>;
+    /** Extension categories. */
+    categories: string[];
+    /** Extension tags / keywords. */
+    tags: string[];
+    /** Extension kind (e.g., `['ui', 'workspace']`). */
+    extensionKind: string[];
+    /** License identifier (e.g., `'MIT'`). May be absent. */
+    license?: string;
+    /** Homepage URL. May be absent. */
+    homepage?: string;
+    /** Repository URL. May be absent. */
+    repository?: string;
+    /** Bug tracker URL. May be absent. */
+    bugs?: string;
+    /** Sponsor link URL. May be absent. */
+    sponsorLink?: string;
+    /** Gallery banner color. May be absent. */
+    galleryColor?: string;
+    /** Gallery banner theme. May be absent. */
+    galleryTheme?: string;
+    /** Localized languages. */
+    localizedLanguages: string[];
+    /** Hard dependency extension IDs. */
+    dependencies: string[];
+    /** Bundled extension IDs. */
+    bundledExtensions: string[];
+    /** Platform-specific download URLs (platform → VSIX URL). */
+    downloads: Record<string, string>;
+}
+/**
+ * Request parameters for `GET /api/-/query`.
+ */
+interface OpenVSXQueryParams {
+    /** Filter by namespace name. */
+    namespaceName?: string;
+    /** Filter by extension name. */
+    extensionName?: string;
+    /** Filter by version string. */
+    extensionVersion?: string;
+    /** Filter by `namespace.name` extension ID. */
+    extensionId?: string;
+    /** Filter by extension UUID. */
+    extensionUuid?: string;
+    /** Filter by namespace UUID. */
+    namespaceUuid?: string;
+    /** Include all versions (default: false). */
+    includeAllVersions?: boolean;
+    /** Filter by target platform. */
+    targetPlatform?: OpenVSXTargetPlatform;
+    /** Number of results per page (default: 100). */
+    size?: number;
+    /** Zero-based page offset (default: 0). */
+    offset?: number;
+}
+/**
+ * Response from `GET /api/-/query`.
+ */
+interface OpenVSXQueryResult {
+    /** Echo of the requested offset. */
+    offset: number;
+    /** Total number of matching extensions. */
+    totalSize: number;
+    /** Full extension metadata objects. */
+    extensions: OpenVSXExtension[];
+}
+/**
+ * Namespace information from `GET /api/{namespace}`.
+ */
+interface OpenVSXNamespace {
+    /** Namespace name (e.g., `'ms-python'`). */
+    name: string;
+    /** Map of extension name → API URL. */
+    extensions: Record<string, string>;
+    /** Whether the namespace is verified. */
+    verified: boolean;
+    /** Access level (e.g., `'restricted'`). */
+    access: string;
+}
+/**
+ * Namespace details from `GET /api/{namespace}/details`.
+ */
+interface OpenVSXNamespaceDetails {
+    /** Namespace name. */
+    name: string;
+    /** Display name. */
+    displayName: string;
+    /** Whether the namespace is verified. */
+    verified: boolean;
+    /** Social media links. */
+    socialLinks: {
+        twitter?: string;
+        linkedin?: string;
+        github?: string;
+    };
+    /** Extensions in this namespace. */
+    extensions: OpenVSXSearchEntry[];
+}
+/**
+ * Response from `GET /api/{namespace}/{extension}/versions`.
+ */
+interface OpenVSXVersionsResult {
+    /** Echo of the requested offset. */
+    offset: number;
+    /** Total number of versions. */
+    totalSize: number;
+    /** Map of version string → API URL. */
+    versions: Record<string, string>;
+}
+/**
+ * A single version reference entry.
+ */
+interface OpenVSXVersionReferenceEntry {
+    /** API URL for this version. */
+    url: string;
+    /** Version string. */
+    version: string;
+    /** Target platform. */
+    targetPlatform: string;
+    /** Engine compatibility. */
+    engines: Record<string, string>;
+    /** File download URLs. */
+    files: Pick<OpenVSXFileMap, 'download' | 'sha256' | 'signature' | 'publicKey'>;
+}
+/**
+ * Response from `GET /api/{namespace}/{extension}/version-references`.
+ */
+interface OpenVSXVersionReferencesResult {
+    /** Echo of the requested offset. */
+    offset: number;
+    /** Total number of version references. */
+    totalSize: number;
+    /** Version reference entries. */
+    versions: OpenVSXVersionReferenceEntry[];
+}
+/**
+ * A single extension review.
+ */
+interface OpenVSXReview {
+    /** Review author. */
+    user: OpenVSXUser;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+    /** Review comment (may be empty). */
+    comment: string;
+    /** Rating (1–5 integer). */
+    rating: number;
+}
+/**
+ * Response from `GET /api/{namespace}/{extension}/reviews`.
+ */
+interface OpenVSXReviewList {
+    /** URL for posting a new review (requires auth). */
+    postUrl: string;
+    /** URL for deleting a review (requires auth). */
+    deleteUrl: string;
+    /** All reviews for this extension. */
+    reviews: OpenVSXReview[];
+}
+/**
+ * Successful API response wrapper.
+ */
+interface OpenVSXApiSuccess<T> {
+    ok: true;
+    data: T;
+}
+/**
+ * Failed API response wrapper.
+ */
+interface OpenVSXApiError {
+    ok: false;
+    /** HTTP status code (0 for network errors). */
+    statusCode: number;
+    /** Error message. */
+    error: string;
+}
+/**
+ * Discriminated union for API responses.
+ */
+type OpenVSXApiResult<T> = OpenVSXApiSuccess<T> | OpenVSXApiError;
+
+/**
+ * Typed client for the Open VSX Registry REST API.
+ *
+ * Provides typed methods for searching, querying, and fetching extension
+ * metadata from Open VSX. Uses the global `fetch` API with an injectable
+ * override for testing.
+ *
+ * @see https://open-vsx.org/api
+ * @see https://github.com/eclipse/openvsx/wiki/Using-the-Registry-API
+ */
+
+/** Configuration options for the Open VSX client. */
+interface OpenVSXClientOptions {
+    /** Base URL for the Open VSX API (default: `'https://open-vsx.org/api'`). */
+    baseUrl?: string;
+    /** Custom `fetch` implementation (default: `globalThis.fetch`). */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Typed client for the Open VSX Registry REST API.
+ *
+ * All methods return a discriminated union `OpenVSXApiResult<T>` — either
+ * `{ ok: true, data: T }` on success or `{ ok: false, statusCode, error }`
+ * on failure. No exceptions are thrown for API or network errors.
+ *
+ * @example
+ * ```typescript
+ * const client = new OpenVSXClient()
+ * const result = await client.search({ query: 'python' })
+ * if (result.ok) {
+ *   console.log(result.data.extensions)
+ * }
+ * ```
+ */
+declare class OpenVSXClient {
+    private readonly baseUrl;
+    private readonly fetch;
+    constructor(options?: OpenVSXClientOptions);
+    /**
+     * Search extensions by text query.
+     *
+     * @param params - Search parameters (query, category, sort, pagination)
+     * @returns Paginated search results
+     */
+    search(params?: OpenVSXSearchParams): Promise<OpenVSXApiResult<OpenVSXSearchResult>>;
+    /**
+     * Query extensions with structured field matching.
+     *
+     * @param params - Query parameters (namespace, extension name, ID, UUID, etc.)
+     * @returns Paginated query results with full extension metadata
+     */
+    query(params?: OpenVSXQueryParams): Promise<OpenVSXApiResult<OpenVSXQueryResult>>;
+    /**
+     * Get extension metadata (latest version or specific version).
+     *
+     * @param namespace - Publisher namespace (e.g., `'ms-python'`)
+     * @param name - Extension name (e.g., `'python'`)
+     * @param version - Specific version string (omit for latest)
+     * @param targetPlatform - Target platform filter
+     * @returns Full extension metadata
+     */
+    getExtension(namespace: string, name: string, version?: string, targetPlatform?: string): Promise<OpenVSXApiResult<OpenVSXExtension>>;
+    /**
+     * Get namespace information with extension listing.
+     *
+     * @param namespace - Namespace name (e.g., `'ms-python'`)
+     * @returns Namespace with map of extension name → API URL
+     */
+    getNamespace(namespace: string): Promise<OpenVSXApiResult<OpenVSXNamespace>>;
+    /**
+     * Get namespace details including display name, social links, and extensions.
+     *
+     * @param namespace - Namespace name
+     * @returns Namespace details with social links and extension summaries
+     */
+    getNamespaceDetails(namespace: string): Promise<OpenVSXApiResult<OpenVSXNamespaceDetails>>;
+    /**
+     * List extension versions with pagination.
+     *
+     * @param namespace - Publisher namespace
+     * @param name - Extension name
+     * @param params - Pagination and platform filter options
+     * @returns Paginated version listing (version string → API URL)
+     */
+    getVersions(namespace: string, name: string, params?: {
+        size?: number;
+        offset?: number;
+        targetPlatform?: string;
+    }): Promise<OpenVSXApiResult<OpenVSXVersionsResult>>;
+    /**
+     * List version references with engine compatibility and file URLs.
+     *
+     * @param namespace - Publisher namespace
+     * @param name - Extension name
+     * @param params - Pagination and platform filter options
+     * @returns Paginated version references
+     */
+    getVersionReferences(namespace: string, name: string, params?: {
+        size?: number;
+        offset?: number;
+        targetPlatform?: string;
+    }): Promise<OpenVSXApiResult<OpenVSXVersionReferencesResult>>;
+    /**
+     * Get all reviews for an extension.
+     *
+     * @param namespace - Publisher namespace
+     * @param name - Extension name
+     * @returns Review list with all reviews (not paginated)
+     */
+    getReviews(namespace: string, name: string): Promise<OpenVSXApiResult<OpenVSXReviewList>>;
+    /**
+     * Build a VSIX download URL for a specific extension version.
+     *
+     * This is a pure URL builder — no network request is made.
+     *
+     * @param namespace - Publisher namespace
+     * @param name - Extension name
+     * @param version - Version string
+     * @param targetPlatform - Target platform (omit for universal)
+     * @returns Full download URL
+     */
+    getDownloadUrl(namespace: string, name: string, version: string, targetPlatform?: string): string;
+    /**
+     * Build a URL for accessing an extension file (README, icon, etc.).
+     *
+     * This is a pure URL builder — no network request is made.
+     *
+     * @param namespace - Publisher namespace
+     * @param name - Extension name
+     * @param version - Version string
+     * @param filePath - Relative file path within the extension
+     * @param targetPlatform - Target platform (omit for universal)
+     * @returns Full file URL
+     */
+    resolveFileUrl(namespace: string, name: string, version: string, filePath: string, targetPlatform?: string): string;
+    /** Build a full URL with optional query parameters. */
+    private _buildUrl;
+    /** Execute a GET request and return a typed result. */
+    private _get;
+}
+
+/** Federation mode determining upstream behavior. */
+type FederationMode = 'proxy' | 'mirror' | 'standalone';
+/** Filter criteria applied to upstream extensions. */
+interface FederationFilter {
+    /**
+     * Only allow declarative extensions (no runtime code needed).
+     *
+     * **Note:** This filter requires `contributionPoints` to be supplied
+     * externally (e.g., from VSIX scanning). When contribution points are
+     * not available (as in `search()` and `getExtension()` which only have
+     * API metadata), this filter is skipped for that extension.
+     */
+    declarativeOnly?: boolean;
+    /** Whitelist of allowed categories (empty array = all allowed). */
+    allowedCategories?: string[];
+    /** Blacklist of publisher namespaces. */
+    blockedPublishers?: string[];
+}
+/** Federation client configuration. */
+interface FederationConfig {
+    /** Federation mode. */
+    mode: FederationMode;
+    /** Upstream registry URL (default: `'https://open-vsx.org/api'`). */
+    upstream?: string;
+    /** Filter configuration. */
+    filter?: FederationFilter;
+    /** Cache TTL hint in seconds for consumers (default: 3600). */
+    cacheTtlSeconds?: number;
+}
+/** A deterministic cache key with suggested TTL. */
+interface FederationCacheKey {
+    /** Deterministic cache key string. */
+    key: string;
+    /** Suggested TTL in seconds. */
+    ttlSeconds: number;
+}
+/** Result of a federated search operation. */
+interface FederatedSearchResult {
+    /** Extensions that passed all filters. */
+    extensions: OpenVSXSearchEntry[];
+    /** Total result count from upstream (before filtering). */
+    totalSize: number;
+    /** Count of extensions removed by filters. */
+    filtered: number;
+    /** Where the data came from. */
+    source: 'upstream' | 'cache' | 'local';
+    /** Cache key for this request. */
+    cacheKey: FederationCacheKey;
+}
+/** Result of a federated extension lookup. */
+interface FederatedExtensionResult {
+    /** The extension, or null if not found or filtered. */
+    extension: OpenVSXExtension | null;
+    /** Whether the extension was blocked by filters. */
+    filtered: boolean;
+    /** Reason the extension was filtered. */
+    filterReason?: string;
+    /** Where the data came from. */
+    source: 'upstream' | 'cache' | 'local';
+    /** Cache key for this request. */
+    cacheKey: FederationCacheKey;
+}
+/**
+ * Generate a deterministic cache key from an endpoint and sorted params.
+ *
+ * @param endpoint - API endpoint name (e.g., `'search'`, `'extension'`)
+ * @param params - Key-value parameters to include in the key
+ * @returns Deterministic cache key string
+ */
+declare function generateCacheKey(endpoint: string, params?: Record<string, string>): string;
+/**
+ * Check if an extension passes all filter criteria.
+ *
+ * @param extension - Extension metadata to check
+ * @param filter - Filter criteria to apply
+ * @param contributionPoints - Contribution point keys from the extension manifest
+ * @returns Whether the extension is allowed and the reason if not
+ */
+declare function matchesFilter(extension: {
+    categories?: string[];
+    namespace?: string;
+    name?: string;
+}, filter: FederationFilter, contributionPoints?: string[]): {
+    allowed: boolean;
+    reason?: string;
+};
+/**
+ * Check if an extension uses only declarative contribution points.
+ *
+ * @param contributionPoints - Contribution point keys from the extension manifest
+ * @returns True if all contribution points are declarative
+ */
+declare function isDeclarativeExtension(contributionPoints: string[]): boolean;
+/**
+ * Federation protocol client that wraps `OpenVSXClient` with mode-based
+ * behavior, filter application, and cache key generation.
+ */
+declare class FederationClient {
+    private readonly config;
+    private readonly upstream;
+    private readonly cacheTtl;
+    /**
+     * Create a new federation client.
+     *
+     * @param config - Federation configuration
+     * @param upstreamClient - Optional pre-configured OpenVSXClient (created from config if not provided)
+     */
+    constructor(config: FederationConfig, upstreamClient?: OpenVSXClient);
+    /**
+     * Search extensions with filters applied.
+     *
+     * In standalone mode, returns empty results. In proxy/mirror mode,
+     * delegates to upstream and applies filters.
+     */
+    search(params?: OpenVSXSearchParams): Promise<OpenVSXApiResult<FederatedSearchResult>>;
+    /**
+     * Get a single extension with filter check.
+     *
+     * In standalone mode, returns null. In proxy/mirror mode,
+     * fetches from upstream and checks against filters.
+     */
+    getExtension(namespace: string, name: string, version?: string): Promise<OpenVSXApiResult<FederatedExtensionResult>>;
+    /**
+     * Get a VSIX download URL for a specific extension version.
+     *
+     * Returns null in standalone mode (no upstream available).
+     */
+    getDownloadUrl(namespace: string, name: string, version: string, targetPlatform?: string): string | null;
+    /**
+     * Build a cache key for a given endpoint and parameters.
+     */
+    getCacheKey(endpoint: string, params?: Record<string, string>): FederationCacheKey;
+    /**
+     * Get a readonly copy of the current federation configuration.
+     */
+    getConfig(): Readonly<FederationConfig>;
+    /** Convert search params to a plain Record for cache key generation. */
+    private _searchParamsToRecord;
+}
+
+export { type AuthenticationContribution, type Badge, type BreakpointContribution, type BugsReference, type CodeActionContribution, type CodeActionKindEntry, type ColorContribution, type ColorDefaults, type CommandContribution, type CompatibilityLevel, type CompatibilityReport, type CompatibilityScore, type ConfigurationContribution, type ConfigurationPropertySchema, type ConfigurationScope, type ContributionPointScore, type CustomEditorContribution, type CustomEditorPriority, type CustomEditorSelector, DECLARATIVE_CONTRIBUTION_POINTS, type DebugConfigurationSnippet, type DebuggerContribution, type DependencyEdge, type DependencyGraph, type DependencyResolution, type DependencyResolutionError, type DependencyResolutionSuccess, type EditPresentation, type ExtensionCapabilities, type ExtensionCategory, type ExtensionKind, type ExtensionNode, type ExtensionRegistry, type ExtensionScope, type ExtensionSource, type FederatedExtensionResult, type FederatedSearchResult, type FederationCacheKey, FederationClient, type FederationConfig, type FederationFilter, type FederationMode, type FileLocationKind, type FlowStateManifest, type GrammarContribution, type IconContribution, type IconDefault, type IconDefinition, type IconReference, type IconThemeContribution, type InstalledExtension, type JsonSchemaType, type JsonValidationContribution, type KeybindingContribution, type LanguageContribution, type LanguageIcon, type LocalizationContribution, type LocalizationTranslation, type LocalizedString, type MenuContribution, type NotebookContribution, type NotebookRendererContribution, type NotebookRendererMessaging, type NotebookSelector, type OpenVSXApiError, type OpenVSXApiResult, type OpenVSXApiSuccess, OpenVSXClient, type OpenVSXClientOptions, type OpenVSXExtension, type OpenVSXFileMap, type OpenVSXNamespace, type OpenVSXNamespaceDetails, type OpenVSXQueryParams, type OpenVSXQueryResult, type OpenVSXReview, type OpenVSXReviewList, type OpenVSXSearchEntry, type OpenVSXSearchParams, type OpenVSXSearchResult, type OpenVSXSearchSortBy, type OpenVSXTargetPlatform, type OpenVSXUser, type OpenVSXVersionReferenceEntry, type OpenVSXVersionReferencesResult, type OpenVSXVersionsResult, PLATFORM_SUPPORT, type Platform, type ProblemApplyTo, type ProblemBackground, type ProblemMatcherContribution, type ProblemPatternContribution, type ProblemSeverity, type ProductIconThemeContribution, type RepositoryReference, type ResourceLabelFormatterContribution, SUPPORT_WEIGHTS, type SemanticTokenModifierContribution, type SemanticTokenScopeContribution, type SemanticTokenTypeContribution, type SnippetContribution, type StartEntryContribution, type SubmenuContribution, type SupportStatus, type TaskDefinitionContribution, type TerminalContribution, type TerminalProfile, type ThemeContribution, type TypescriptServerPluginContribution, type UITheme, type UntrustedWorkspaceCapability, type VSCodeContributes, type VSCodeExtensionManifest, type ViewContainerContribution, type ViewContribution, type ViewType, type ViewVisibility, type ViewWelcomeContribution, type VirtualWorkspaceCapability, VsixScanError, type VsixScanErrorCode, type VsixScanResult, type WalkthroughContribution, type WalkthroughStepContribution, type WalkthroughStepMedia, buildCompatibilityReport, buildDependencyGraph, classifyDeclarative, detectApiNamespaces, enumerateContributionPoints, extractDependencyNode, flowStateToVsCode, generateCacheKey, generateRecommendations, getPlatformSupport, isDeclarativeExtension, mapActivationEvents, mapCategory, mapExtensionKind, matchesFilter, normalizeExtensionId, resolveDependencies, reverseActivationEvents, reverseCategory, reverseExtensionKind, scanVsix, scoreExtension, vsCodeToFlowState };