// src/flow/IShellRegistry.ts

import type { IShellInfo } from './ShellRegistry';

/**
 * Interface for shell info registry (instance-based).
 *
 * ═══════════════════════════════════════════════════════════════════════════
 * COLLECTOR PATTERN (Expert Panel 2024-12)
 * ═══════════════════════════════════════════════════════════════════════════
 *
 * Joe Duffy (Midori OS):
 *   "Separate 'collect metadata' from 'consume metadata'. Decorators
 *    collect to a static queue; runtime consumes into an instance."
 *
 * This interface represents the CONSUMER side of the Collector Pattern:
 * - Decorators write to `ShellRegistry._pendingRegistrations` (static, write-only)
 * - `ShellRegistryComponent` implements this interface (instance, read-write)
 * - On bootstrap, component drains the pending queue and becomes authority
 *
 * This enables:
 * - Instance-based lookups (for test isolation)
 * - Multiple registries for different contexts
 * - Clean separation of collection and consumption
 * - No ambient authority - component must be passed explicitly
 *
 * Mark Miller (Capability Security):
 *   "The interface represents the capability to access the registry.
 *    Only code with a reference can query it. No global lookup."
 * ═══════════════════════════════════════════════════════════════════════════
 */
export interface IShellRegistry {
  /**
   * Register shell info for a component type.
   *
   * Called via Matrix protocol (not decorators - those use static queue).
   *
   * @param componentClass - Component class name
   * @param info - Shell rendering info
   */
  register(componentClass: string, info: IShellInfo): void;

  /**
   * Look up shell info for a component type.
   *
   * @param componentClass - Component class name
   * @returns Shell info or undefined if not registered
   */
  lookup(componentClass: string): IShellInfo | undefined;

  /**
   * Check if a component type has registered shell info.
   *
   * @param componentClass - Component class name
   * @returns true if registered
   */
  has(componentClass: string): boolean;

  /**
   * Get all registered component types.
   *
   * @returns Array of registered component class names
   */
  getRegisteredTypes(): string[];

  /**
   * Clear all registrations.
   * Primarily for testing.
   */
  clear(): void;
}