<?php

declare(strict_types=1);

/**
 * Stable public contract for Myron Insert Code ([mic]) element resolvers.
 */
interface MicElementResolverInterface
{
    /**
     * Resolve one mic element to pre-blessed HTML.
     *
     * @apiVersion 1
     * @param array{pageId?:string,fieldKey?:string,channel?:string,userScopes?:list<string>} $context
     */
    public function resolve(string $id, array $context): ?string;

    /**
     * Describe the element type for Content Banks, toolbar pickers, and MCP.
     *
     * @apiVersion 1
     * @return array{
     *   slug:string,
     *   label:string,
     *   description:string,
     *   icon:string,
     *   scopes:list<string>,
     *   bankSurface:'editor'|'picker'|'none',
     *   parentSurfaceUrl?:string,
     *   adminUrl?:string
     * }
     */
    public function describe(): array;
}

