import { DataContract, GadgetDescriptor, BlueprintVariance } from '@ggui-ai/protocol';

/**
 * Contract + rendering-context prompt rendering.
 *
 * Surfaces every contract dimension explicitly to the LLM. A compact
 * bullet list of action / stream names is not enough — without the
 * Props shape, generation fails tier-0 on most cells with "Props
 * interface missing required field '<name>'".
 *
 * Renders:
 *
 *   - Props contract — required + optional field lists + a real
 *     TypeScript interface (compiled via `propsSpecToTypeScript`)
 *   - Action contract — id / label / example / nextStep hint
 *   - Stream contract — channel descriptions + payload schemas + source
 *   - AgentTools — catalog of tools the contract references (via
 *     `actionSpec[*].nextStep` and `streamSpec[*].source.tool`)
 *   - ClientCapabilities — browser-capability gadgets the UI mounts:
 *     hooks it calls (e.g. `useGeolocation` from `@ggui-ai/gadgets`)
 *     and components it renders (e.g. `<LeafletMap />`)
 *   - Required UI Surfaces — derived list of "every contract surface
 *     must have visible UI" so the LLM doesn't drop required props or
 *     skip rendering data sources
 *
 * Rendering context (device + shell + viewport) is layered alongside —
 * shells (`chat` / `fullscreen` / `partial`) require very different
 * sizing strategies and including the hint inline cuts a class of
 * "designed for fullscreen, rendered in a chat bubble" bugs.
 */

/**
 * Rendering context — how and where the component will be displayed.
 * Affects layout strategy, sizing, and interaction patterns. Mirrors the
 * shape cloud's harness passes through `dispatchGeneration`.
 */
interface RenderingContext {
    /** Device category — affects touch targets, column count, density. */
    readonly device: 'mobile' | 'tablet' | 'desktop' | 'spatial';
    /** Shell type — the container the component renders in. */
    readonly shell: 'chat' | 'fullscreen' | 'partial';
    /** Viewport dimensions in CSS pixels (optional). */
    readonly viewport?: {
        readonly width: number;
        readonly height: number;
    };
}
/** Build rendering-context block to inject into user prompt. */
declare function buildRenderingContext(ctx: RenderingContext): string;
/** Append rendering context to user prompt if present. */
declare function injectRenderingContext(userPrompt: string, rendering?: RenderingContext): string;
/**
 * Build the contract-context block. Surfaces every dimension of the
 * contract so the LLM has a complete spec rather than the user-prompt
 * narrative alone — the eval scores against the contract regardless of
 * what prose the prompt carries, so contract-first rendering closes
 * the prompt-vs-contract drift class.
 */
declare function buildContractsContext(contract: DataContract, 
/**
 * Operator-registered gadget catalog. When a
 * `clientCapabilities.gadgets[*]` ref is THIN (just `{hook}` —
 * no per-binding `package`), look the hook up here to surface the
 * correct package in user-prompt lines like `via useLeafletMap from
 * @ggui-samples/gadget-leaflet`. Mirrors the same plumb in
 * `harness/prompts.ts:buildContractsContext` — both surfaces are
 * separate copies used by different call sites (this one is for
 * `createUiGenerator`, the other for the benchmark / dispatch path).
 */
appGadgets?: readonly GadgetDescriptor[]): string;
/**
 * Append the contract-context block to a user prompt if a contract is present.
 *
 * `appGadgets` forwards into `buildContractsContext` so thin contract
 * refs (`{hook}` without per-binding `package`) resolve to the
 * registered descriptor's package in the prompt-emitted "import X from
 * Y" lines.
 */
declare function injectContracts(userPrompt: string, contract?: DataContract, appGadgets?: readonly GadgetDescriptor[]): string;
/**
 * Build the variance-context block. Surfaces the agent's declared
 * styling signals (persona, aesthetic, context, seedPrompt) so cold-gen
 * aligns the produced component with the requested variant. Each field
 * is optional; the block only renders when at least one is present.
 *
 * - `persona` names the USER mental model (e.g. "data-analyst",
 *   "mobile-first reader") — drives copy register + density choices.
 * - `aesthetic` names the VISUAL treatment (e.g. "glassmorphic",
 *   "editorial", "brutalist") — drives surface decoration, typographic
 *   weight, color usage.
 * - `context` is structured key-value signal alongside the persona —
 *   small JSON-safe shape, serialized verbatim into the prompt.
 * - `seedPrompt` is the operator's original natural-language steer that
 *   produced this variant in cache storage — useful as a one-line
 *   directive for cold-gen.
 *
 * Returns an empty string when no fields are populated so the inject
 * helper can no-op cleanly.
 */
declare function buildVarianceContext(variance: BlueprintVariance): string;
/** Append the variance-context block to a user prompt if variance is present. */
declare function injectVariance(userPrompt: string, variance?: BlueprintVariance): string;

export { type RenderingContext as R, buildRenderingContext as a, buildContractsContext as b, buildVarianceContext as c, injectRenderingContext as d, injectVariance as e, injectContracts as i };