export interface RenderBulbResult {
  /** Complete standalone HTML document, ready for an iframe srcdoc. */
  html?: string
  /** Set instead of `html` when the source couldn't be rendered. */
  error?: string
}

/** Compile a bulb source string to a standalone HTML document (client-only).
 *  Pass `theme` to force the embed's light/dark mode (e.g. match the host). */
export declare function renderBulb(source: string, opts?: { theme?: 'light' | 'dark' }): Promise<RenderBulbResult>

export interface BulbFrameOptions {
  /** Force light/dark. Omit to inherit the host's `data-theme` automatically. */
  theme?: 'light' | 'dark'
  /** Height shown before the embed reports its content height, and the height a
   *  full-bleed (`height:100%`) bulb settles at. Flow content settles above OR below
   *  this to its true height. Default 320. */
  initialHeight?: number
  /** Ceiling for auto-height; bounds an absurd height from a buggy/hostile embed. Default 100000. */
  maxHeight?: number
  /** Called with a message when the embed throws at runtime (post-mount). */
  onError?: (message: string) => void
  /** Called once, on the embed's first auto-height report — the bulb's code ran to first
   *  paint. Skipped if an error arrives first, so ready never follows a failure. */
  onReady?: () => void
  /** Abort to remove the frame's host-side `message` listener (host owns lifecycle). */
  signal?: AbortSignal
}

/** Render a bulb and return a ready-to-mount, sandboxed iframe: owns the
 *  `allow-scripts` sandbox policy and the host<->embed protocol (auto-height +
 *  runtime-error forwarding). Rejects if the bulb can't compile. */
export declare function createBulbFrame(source: string, opts?: BulbFrameOptions): Promise<HTMLIFrameElement>

/** The bulb's `name:` from its leading frontmatter, or undefined if absent. */
export declare function bulbName(source: string): string | undefined

/** A filesystem-safe slug from the bulb's name; 'bulb' when unnamed. */
export declare function slugifyBulbName(source: string): string

/** The source with its leading `---` frontmatter block stripped. */
export declare function stripFrontmatter(source: string): string

/** Structural problems a bulb's Markdown has (chiefly an unterminated fence that swallowed a block);
 *  one message per problem, empty when well-formed. */
export declare function validateBulbStructure(content: string): string[]