/**
 * Tool Context Types
 *
 * Defines the context types passed to tools for making visibility and behavior decisions.
 * Each context level provides increasingly specific information about where the tool is being used.
 */
import type { AssessmentEntity, AssessmentItemRef, AssessmentSection, ItemEntity, PassageEntity, RubricBlock } from "@pie-players/pie-players-shared/types";
/**
 * Tool placement levels - where a tool can appear in the UI
 */
export type ToolLevel = "assessment" | "section" | "item" | "passage" | "rubric" | "element";
/**
 * Base context available to all tools
 */
export interface BaseToolContext {
    /** The level at which this tool is being evaluated */
    level: ToolLevel;
    /** The full assessment entity */
    assessment: AssessmentEntity;
    /** Current section, if applicable */
    section?: AssessmentSection;
    /** Reference to the current item (always available except at assessment level) */
    itemRef?: AssessmentItemRef;
    /** DOM container where the tool will be rendered */
    container?: HTMLElement;
}
/**
 * Context for assessment-level tools
 */
export interface AssessmentToolContext extends BaseToolContext {
    level: "assessment";
}
/**
 * Context for section-level tools
 */
export interface SectionToolContext extends BaseToolContext {
    level: "section";
    section: AssessmentSection;
}
/**
 * Context for item-level tools (question toolbar)
 */
export interface ItemToolContext extends BaseToolContext {
    level: "item";
    itemRef: AssessmentItemRef;
    item: ItemEntity;
    /** Passage entity if this item is associated with a passage */
    passage?: PassageEntity;
}
/**
 * Context for passage-level tools (passage header)
 *
 * Passages can appear as:
 * - Standalone passage entities associated with items
 * - RubricBlock with class="stimulus" containing embedded passage
 */
export interface PassageToolContext extends BaseToolContext {
    level: "passage";
    itemRef?: AssessmentItemRef;
    passage: PassageEntity;
    /** Items associated with this passage (if applicable) */
    items?: ItemEntity[];
    /** RubricBlock containing this passage (if from rubric) */
    rubricBlock?: RubricBlock;
}
/**
 * Context for rubric block tools
 *
 * RubricBlocks can contain:
 * - Instructions (class="instructions")
 * - Rubrics (class="rubric")
 * - Stimulus/passages (class="stimulus" with embedded passage)
 * - Simple HTML content
 */
export interface RubricToolContext extends BaseToolContext {
    level: "rubric";
    rubricBlock: RubricBlock;
    /** Section containing this rubric block */
    section: AssessmentSection;
    /** If rubric contains a passage (class="stimulus") */
    passage?: PassageEntity;
}
/**
 * Context for element-level tools (inline with interaction)
 *
 * Note: Element-level context uses the PIE interaction element ID
 * and provides access to the full item config for content inspection.
 */
export interface ElementToolContext extends BaseToolContext {
    level: "element";
    itemRef: AssessmentItemRef;
    item: ItemEntity;
    /** The PIE element/interaction ID */
    elementId: string;
    /** Passage entity if this item is associated with a passage */
    passage?: PassageEntity;
    /** DOM element that triggered the tool (e.g., the specific input field) */
    triggerElement?: HTMLElement;
}
/**
 * Union type of all tool contexts
 */
export type ToolContext = AssessmentToolContext | SectionToolContext | ItemToolContext | PassageToolContext | RubricToolContext | ElementToolContext;
/**
 * Type guard to check if context is at assessment level
 */
export declare function isAssessmentContext(context: ToolContext): context is AssessmentToolContext;
/**
 * Type guard to check if context is at section level
 */
export declare function isSectionContext(context: ToolContext): context is SectionToolContext;
/**
 * Type guard to check if context is at item level
 */
export declare function isItemContext(context: ToolContext): context is ItemToolContext;
/**
 * Type guard to check if context is at passage level
 */
export declare function isPassageContext(context: ToolContext): context is PassageToolContext;
/**
 * Type guard to check if context is at rubric level
 */
export declare function isRubricContext(context: ToolContext): context is RubricToolContext;
/**
 * Type guard to check if context is at element level
 */
export declare function isElementContext(context: ToolContext): context is ElementToolContext;
/**
 * Helper to extract text content from an item or element for analysis
 */
export declare function extractTextContent(context: ToolContext): string;
/**
 * Helper to check if context contains mathematical content
 * (Basic heuristic - can be overridden by tools)
 */
export declare function hasMathContent(context: ToolContext): boolean;
/**
 * Helper to check if context contains choice-based interactions
 */
export declare function hasChoiceInteraction(context: ToolContext): boolean;
/**
 * Helper to check if context contains text that can be read aloud
 */
export declare function hasReadableText(context: ToolContext): boolean;
/**
 * Helper to check if context contains science content
 * (Basic heuristic - can be overridden by tools)
 */
export declare function hasScienceContent(context: ToolContext): boolean;
