@aihu/plugin

function definePlugin(config: PluginConfig): Plugin

Define a aihu plugin.

function resetValidationState(): void

Reset the duplicate-namespace tracker.

function validatePlugin(plugin: Plugin): ValidationResult

Validate a plugin per spec §8.1.

const AIHU_VERSION

Current aihu framework version against which `aihuVersion` ranges are checked.

const RESERVED_NAMESPACES: ReadonlyArray<string>

Reserved plugin namespaces per spec §1.3.

interface BlockContext extends SfcContext {
  readonly blockType: string
  readonly blockName: string
}

Per-block context provided to `transformBlock` hooks and macro lowering (spec §4.2, §5.2).

interface BuildContext {
  /** Resolved plugin configuration (per spec §3). */
  readonly config: Readonly<Record<string, unknown>>
  readonly mode: BuildMode
  readonly outputDir: string
  readonly projectRoot: string
}

Build-time context provided to `beforeCompile` hooks (spec §4.2).

interface ConfigFieldSpec {
  readonly type: ConfigFieldType
  readonly default?: unknown
  readonly description?: string
}

interface Contributes {
  readonly blocks?: ReadonlyArray<string>
  readonly macros?: ReadonlyArray<Macro>
  readonly components?: ReadonlyArray<string>
  readonly transforms?: ReadonlyArray<Transform>
  /** Server-only runtime helpers (spec §6.5.1). */
  readonly serverRuntime?: ServerRuntime
  /** Server middleware (spec §6.5.3, provisional). */
  readonly middleware?: ReadonlyArray<Middleware>
}

Plugin contributions (spec §2 + §6.5).

interface Hooks {
  readonly beforeCompile?: BeforeCompileHook
  readonly afterParse?: AfterParseHook
  readonly transformBlock?: TransformBlockHook
  readonly afterCompile?: AfterCompileHook
}

interface ImportSpec {
  readonly from: string
  readonly names: ReadonlyArray<string>
}

interface LoweringResult {
  readonly code: string
  readonly imports?: ReadonlyArray<ImportSpec>
  readonly hoist?: ReadonlyArray<string>
  /**
   * Explicit emission target per Block Structure Spec §11.5. When omitted,
   * the compiler infers based on enclosing context.
   */
  readonly target?: BuildTarget
}

Complex emission result for macros that emit multiple statements or require imports/hoisted declarations (spec §5.3).

interface Macro {
  readonly name: string
  readonly validIn: ReadonlyArray<string>
  readonly lowering: MacroLowering
  readonly validation?: MacroValidation
  /**
   * When true, the macro emits server-only output (per spec §6.5.2): the
   * lowered output goes to the server artifact and is elided from the client
   * bundle. (The `$server` macro that this once mirrored has been retired —
   * see Macro Vocabulary spec §2.12.)
   */
  readonly serverOnly?: boolean
}

Macro contribution declaration (spec §2.2).

interface MacroContext {
  readonly pluginConfig: Readonly<Record<string, unknown>>
  readonly sfc: SfcContext
  readonly block: BlockContext
  /** Request an import. Returns the local name to use in emitted code. */
  readonly imports: (spec: string) => string
  /** Request a runtime helper. Returns the local name to use in emitted code. */
  readonly runtime: (name: string) => string
}

Macro lowering context (spec §5.2).

interface Middleware {
  readonly name: string
  readonly stage: MiddlewareStage
  /** Path to the middleware handler module, relative to the plugin root. */
  readonly handler: string
}

interface Plugin extends PluginConfig {
  /** Brand to distinguish constructed plugins from raw config objects. */
  readonly __aihu_plugin: true
}

Plugin instance — the registered, validated plugin.

interface PluginConfig {
  readonly name: string
  readonly version: string
  readonly namespace: string
  /** Compatible aihu versions (semver range). Checked at registration (spec §7.3). */
  readonly aihuVersion?: string
  readonly configSchema?: ConfigSchema
  readonly contributes?: Contributes
  readonly hooks?: Hooks
  readonly parsers?: Readonly<Record<string, BlockParser>>
  /** Other plugin namespaces this plugin depends on (spec §10.1). */
  readonly dependencies?: ReadonlyArray<string>
  /**
   * If `true`, this plugin's contributions are lowered to the server bundle
   * only (Amendment 03 §6.5). Client code that references server-only
   * contributions receives RPC stubs instead of the real implementation.
   * PROVISIONAL in v1.0 — behaviour may evolve through the v1.x series.
   */
  readonly serverOnly?: boolean
}

Plugin definition input — what authors pass to `definePlugin`.

interface SfcContext extends BuildContext {
  readonly sfcPath: string
  readonly componentName: string
  /**
   * Symbol table contents (per Block Structure Spec §11.3). Opaque shape
   * here; the compiler defines exact contents.
   */
  readonly symbolTable: Readonly<Record<string, unknown>>
}

Per-SFC compilation context provided to `afterParse` and `afterCompile` hooks (spec §4.2).

interface Transform {
  readonly stage: TransformStage
  readonly fn: (input: unknown) => unknown
}

interface ValidationError {
  /** Stable error code corresponding to a row in spec §8.1 / §8.2. */
  readonly code:
    | 'invalid-namespace'
    | 'reserved-namespace'
    | 'duplicate-namespace'
    | 'missing-required-field'
    | 'aihu-version-mismatch'
  readonly message: string
}

type AfterCompileHook = (
  ctx: SfcContext,
  output: unknown,
) => Promise<unknown | undefined> | unknown | undefined

type AfterParseHook = (
  ctx: SfcContext,
  ast: unknown,
) => Promise<unknown | undefined> | unknown | undefined

type BeforeCompileHook = (ctx: BuildContext) => Promise<void> | void

type BlockParser = (body: string, ctx: BlockContext) => unknown

Block parser signature (spec §2.1).

type BuildMode = 'dev' | 'build'

Build mode (dev vs production build).

type BuildTarget = 'client' | 'server' | 'universal'

Build target semantics per Block Structure Spec §11.5.

type ConfigFieldType = 'string' | 'number' | 'boolean' | 'object' | 'array' | 'function'

type ConfigSchema = Readonly<Record<string, ConfigFieldSpec>>

type MacroArgs = Readonly<Record<string, unknown>>

Macro arguments — opaque shape; per-macro semantics.

type MacroLowering = (ctx: MacroContext, args: MacroArgs) => string | LoweringResult

Macro lowering function signature (spec §5.1).

type MacroValidation = (
  ctx: { readonly error: (msg: string) => void },
  args: MacroArgs,
) => void

Macro validation function signature (spec §5.4).

type MiddlewareStage = 'before-handler' | 'after-handler' | 'on-error'

Server middleware contribution (spec §6.5.3).

type ServerRuntime = Readonly<Record<string, string>>

Server-only runtime helper map (spec §6.5.1).

type TransformBlockHook = (
  ctx: BlockContext,
  block: unknown,
) => Promise<unknown | undefined> | unknown | undefined

type TransformStage = 'after-parse' | 'before-lower' | 'after-lower'

Transform stages (spec §2.4).

type ValidationResult =
  | { readonly ok: true }
  | { readonly ok: false; readonly errors: ReadonlyArray<ValidationError> }