@callback compile(path :: String.t(), source :: String.t(), opts :: keyword()) ::
  {:ok, compiled()} | {:error, term()} | nil

Compile a source file into browser-ready JavaScript plus optional CSS.

@callback define(mode :: String.t()) :: %{required(String.t()) => String.t()}

Return compile-time replacements for a build mode.

@callback embedded_modules(path :: String.t(), source :: String.t(), opts :: keyword()) ::
  [{extension :: String.t(), source :: String.t()}] | nil

Return virtual JavaScript-like modules embedded in a plugin-owned source file.

@callback enforce() :: :pre | :post | nil

Return :pre, :post, or nil to control plugin ordering.

@callback extensions(kind :: atom()) :: [String.t()]

Return extensions owned by this plugin for :compile, :resolve, :watch, or :scan.

@callback extract_imports(path :: String.t(), source :: String.t(), opts :: keyword()) ::
  {:ok, Volt.JS.ImportExtractor.Result.t()} | {:error, term()} | nil

Extract dependency metadata from source handled by this plugin.

Use this when a source format can contain imports that are not visible to Volt's normal JavaScript parser before plugin processing, such as component files or custom markup formats. Return nil to let Volt use the default JavaScript import extractor.

@callback load(path :: String.t()) ::
  {:ok, String.t(), String.t()} | {:ok, String.t()} | nil

Load content for a resolved module path.

@callback name() :: String.t()

Plugin name for identification and error messages.

@callback prebundle_alias(specifier :: String.t()) :: String.t() | nil

Return the canonical dev prebundle specifier for an import.

Use this advanced framework-integration hook when several package entrypoints should share one dev vendor module. Return nil to leave the specifier unchanged.

This is Volt-specific. Vite framework plugins achieve similar results through dependency optimization, resolution, and virtual modules rather than a direct hook with this name.

@callback prebundle_entry(specifier :: String.t()) ::
  {:source, filename :: String.t(), source :: String.t()}
  | {:proxy, filename :: String.t(),
     imports: [prebundle_import()], exports: [prebundle_export()]}
  | nil

Return a generated dev prebundle entry for a canonical specifier.

Use this advanced framework-integration hook when a framework needs a synthetic vendor module that re-exports multiple package entrypoints or adapts package exports for browser dev mode. Return nil to let Volt generate a normal package prebundle.

This hook affects dev dependency prebundling only; production output is built from the application module graph.

@callback render_chunk(code :: String.t(), chunk_info :: map()) :: {:ok, String.t()} | nil

Transform a final output chunk before writing.

@callback resolve(specifier :: String.t(), importer :: String.t() | nil) ::
  {:ok, String.t()} | :skip | nil

Resolve an import specifier to a file path, :skip, or pass with nil.

@callback transform(code :: String.t(), path :: String.t()) :: {:ok, String.t()} | nil

Transform compiled JavaScript before serving or bundling.