/**
 * Focus Region Map Utilities
 *
 * Utilities for mapping focus region paths to component IDs
 * and creating focus highlight information from actor presence data.
 */
import type { PuckData, ActorPresence } from '@pantheon-systems/css-client';
import { type AgentIconName } from './actorDisplayName.js';
/**
 * Information about a focus highlight for a component.
 */
export interface FocusHighlight {
    /** Actor ID who has focus on this component */
    actorId: string;
    /** Actor display name */
    actorName: string;
    /** Color to use for highlighting (hex format) */
    color: string;
    /** Whether the actor is actively editing (vs just viewing) */
    isEditing: boolean;
    /** Whether the focus belongs to an AI agent rather than a person */
    isAgent?: boolean;
    /** The icon shown beside an agent's name. Set for agents only */
    agentIcon?: AgentIconName;
    /** Name of the person an agent is acting for, when it was asked to act */
    onBehalfOf?: string;
    /** The turn an agent is working on, when it named one. Distinguishes one run from the next */
    turnId?: string;
}
/**
 * Convert a focus region path to a component ID.
 *
 * Accepts JSON-pointer (`/content/0`) and dot notation (`content.0`), and
 * resolves to the deepest component the path passes through: a prop path names
 * the component owning the prop, and a slot path the nested child. A path
 * naming no component (`content`) resolves to null.
 *
 * @param data - Puck data containing content and zones
 * @param path - Focus region path (e.g., "/content/0" or "content.0.props.title")
 * @returns Component ID if the path passes through one, null otherwise
 *
 * @example
 * ```typescript
 * pathToComponentId(puckData, '/content/0');            // first component in content
 * pathToComponentId(puckData, 'content.0.props.title'); // same component, via its prop
 * pathToComponentId(puckData, '/zones/Header:left/0');  // first component in a zone
 * ```
 */
export declare function pathToComponentId(data: PuckData, path: string): string | null;
/**
 * Create a map of component IDs to focus highlight information.
 *
 * Processes actor presence data to determine which components are being
 * focused on by which actors, including their display info and state.
 *
 * @param data - Puck data containing content and zones
 * @param actors - Array of actor presence information
 * @returns Map from component ID to focus highlight info
 *
 * @example
 * ```typescript
 * const focusMap = createFocusRegionMap(puckData, otherActors);
 *
 * const highlight = focusMap.get('hero-component-1');
 * const label =
 *   highlight === undefined ? 'nobody' : highlight.isEditing ? 'editing' : 'viewing';
 * ```
 */
export declare function createFocusRegionMap(data: PuckData, actors: ActorPresence[]): Map<string, FocusHighlight>;
/**
 * Generate a consistent color from an actor ID.
 *
 * Uses the djb2 hash algorithm to generate a hex color that:
 * - Is deterministic (same ID always produces same color)
 * - Matches the avatar color algorithm in CollaboratorAvatars.tsx
 * - Has consistent saturation (65%) and lightness (45%) for readability
 *
 * @param actorId - Actor identifier
 * @returns Hex color string (e.g., "#6366f1")
 *
 * @example
 * ```typescript
 * const color = generateActorColor('user-alice');
 * // Returns a consistent hex color for this actor
 * ```
 */
export declare function generateActorColor(actorId: string): string;