Option Strict On
Option Explicit On

Imports System
Imports SkiaSharp

Namespace Nexamas.UI.FloatRuntime

    ' ============================================================
    ' MASFloatRuntime Contract
    ' Class: IMASFloatSession
    '
    ' Purpose:
    '   Defines the safe bridge between Float content and MASFloatRuntime.
    '
    ' Responsibility:
    '   Allows content to request completion, failure, close, or Shield
    '   changes without owning lifecycle or accessing internal runtime
    '   services.
    '
    ' Owns:
    '   No public lifecycle execution.
    '   No host state.
    '   No policy state.
    '
    ' Does Not Own:
    '   Final close authorization.
    '   Host removal.
    '   Transition completion.
    '   External callback delivery.
    '
    ' Allowed Dependencies:
    '   MASFloatHandle.
    '   MASFloatCloseReason.
    '   MASFloatShieldOptions.
    '
    ' Forbidden Dependencies:
    '   Legacy Overlay classes.
    '   MASFloatCoordinator concrete type.
    '   MASFloatRuntimeState.
    '   MASFloatHost.
    '   MASFloatPolicyEngine concrete type.
    '
    ' Lifecycle Role:
    '   Exists for the active Float session and is attached to content by
    '   the runtime.
    '
    ' Threading:
    '   Session methods may be called by content during UI interaction.
    '   Runtime implementation must marshal lifecycle work to the UI thread
    '   if needed.
    '
    ' Mutation Rules:
    '   Content may request Accept, Complete, Cancel, Fail, Close, ReleaseShield, or
    '   SetShield through the session.
    '   Content must not mutate handle state directly.
    '
    ' Invariants:
    '   Accept stores an accepted result and requests close.
    '   Complete stores a fully formed result with the caller-owned close reason.
    '   Cancel stores cancelled result and requests close.
    '   Fail stores failed result and requests close or failure handling.
    '   External callbacks must happen only after Closed.
    '
    ' Failure Rules:
    '   Calls made after the session is closed, detached, stale, or disposed
    '   must not mutate newer Float instances.
    ' ============================================================
    Friend Interface IMASFloatSession

        ReadOnly Property Handle As MASFloatHandle

        Sub Accept(result As Object)

        Sub Complete(result As MASFloatResult,
                     closeReason As MASFloatCloseReason)

        Sub Cancel()

        Sub Fail(errorMessage As String)

        Sub Close(reason As MASFloatCloseReason)

        Sub ReleaseShield()

        Sub SetShield(options As MASFloatShieldOptions)

        ReadOnly Property AvailableBoundsPx As SKRect

        Function TryGetBoundsPx(ByRef boundsPx As SKRect) As Boolean

        Function TrySetBoundsPx(boundsPx As SKRect) As Boolean

        ''' <summary>
        ''' Requests repaint of the owning Float host without changing bounds, result, close state,
        ''' or ownership. Continuous interaction systems such as the shared MAS Scroll adapter use
        ''' this route when their internal timer advances visual state after the original pointer event.
        ''' </summary>
        Sub RequestInvalidate()

        ''' <summary>
        ''' Posts control-owned asynchronous work through the root-owned UI dispatcher for this Float session.
        ''' Detached, stale, or hostless sessions return False and must not fall back to a captured context.
        ''' </summary>
        Function PostToUiThread(action As Action,
                                Optional diagnosticName As String = Nothing) As Boolean

    End Interface

End Namespace